[FE] 개발 환경 - woowacourse-teams/2026-gachi-gacha GitHub Wiki
시작하기
1. 저장소 클론
git clone https://github.com/woowacourse-teams/2026-gachi-gacha.git
cd 2026-gachi-gacha/frontend
이 저장소는 프론트엔드와 백엔드를 함께 관리하는 모노레포입니다.
프론트엔드 작업자는 원칙적으로
frontend/디렉터리 안에서만 작업합니다.
2. Node.js 버전 적용
NVM이 설치되어 있다면 .nvmrc에 지정된 Node.js를 설치하고 사용합니다.
nvm install
nvm use
설치된 버전을 확인합니다.
node --version
예상 결과:
v24.19.0
3. pnpm 활성화
프로젝트에서 지정한 pnpm 버전을 활성화합니다.
corepack enable
corepack prepare [email protected] --activate
설치된 버전을 확인합니다.
pnpm --version
예상 결과:
11.9.0
프로젝트의 의존성 일관성을 위해 npm, Yarn, Bun 대신 pnpm을 사용합니다.
4. 의존성 설치
pnpm install --frozen-lockfile
package.json과 pnpm-lock.yaml이 일치하지 않을 경우 설치를 중단합니다. 이를 통해 팀원과 CI가 동일한 의존성 버전을 설치하도록 보장합니다.
코드 품질 검사
ESLint 검사
pnpm lint
자동 수정 가능한 ESLint 오류를 수정합니다.
pnpm lint:fix
Prettier 검사
pnpm format:check
Prettier 형식을 코드에 적용합니다.
pnpm format
TypeScript 검사
JavaScript 파일을 생성하지 않고 TypeScript 타입만 검사합니다.
pnpm typecheck
Storybook 실행
컴포넌트를 독립적으로 개발하고 확인할 때 Storybook을 실행합니다.
pnpm storybook
브라우저에서 다음 주소로 접속합니다.
http://localhost:6006
Storybook 정적 빌드는 다음 명령으로 확인합니다.
pnpm build-storybook
Storybook에서는 MSW가 자동으로 시작됩니다. 현재 예제에서는 다음 API 요청을 모킹합니다.
GET /api/stores
애플리케이션 실행
Webpack 개발 서버는 다음 명령으로 실행합니다.
pnpm dev
기본 접속 주소:
http://localhost:3000
운영용 번들은 다음 명령으로 생성합니다.
pnpm build
빌드 결과는 frontend/dist/에 생성됩니다.
통합 검사
다음 명령은 ESLint, Prettier, TypeScript, Webpack 빌드를 순서대로 실행합니다.
pnpm check
실행 순서:
pnpm lint
→ pnpm format:check
→ pnpm typecheck
→ pnpm build
주요 명령어
| 명령어 | 설명 |
|---|---|
pnpm install --frozen-lockfile |
lockfile 기준 의존성 설치 |
pnpm dev |
Webpack 개발 서버 실행 |
pnpm build |
운영용 애플리케이션 빌드 |
pnpm typecheck |
TypeScript 타입 검사 |
pnpm lint |
ESLint 검사 |
pnpm lint:fix |
ESLint 오류 자동 수정 |
pnpm format |
Prettier 포맷 적용 |
pnpm format:check |
Prettier 적용 여부 검사 |
pnpm check |
전체 품질 검사 및 애플리케이션 빌드 |
pnpm storybook |
Storybook 개발 서버 실행 |
pnpm build-storybook |
Storybook 정적 빌드 |
초기 세팅 디렉터리 구조
frontend/
├── .storybook/
│ ├── main.ts
│ └── preview.ts
├── public/
│ └── mockServiceWorker.js
├── src/
│ └── mocks/
│ ├── browser.ts
│ ├── handlers.ts
│ └── MockedStoreList.stories.tsx
├── .gitignore
├── .nvmrc
├── .prettierignore
├── eslint.config.mjs
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── prettier.config.mjs
├── tsconfig.json
└── webpack.config.cjs
패키지 설치 규칙
패키지는 반드시 frontend/ 디렉터리에서 pnpm으로 설치합니다.
cd frontend
pnpm add 패키지명
개발 과정에서만 사용하는 패키지는 -D 옵션으로 설치합니다.
pnpm add -D 패키지명
Git에 포함하지 않는 파일
다음 파일과 디렉터리는 자동 생성 결과이므로 Git에 포함하지 않습니다.
node_modules/
dist/
storybook-static/
coverage/
MSW가 생성한 다음 파일은 팀원 모두가 동일한 Service Worker를 사용할 수 있도록 Git에 포함합니다.
public/mockServiceWorker.js
커밋 전 확인
커밋하기 전에 최소한 다음 검사를 실행합니다.
pnpm lint
pnpm format:check
pnpm typecheck
React 실행 골격이 구성된 이후에는 통합 검사를 실행합니다.
pnpm check