프런트엔드 개발 환경

dictionary-app 저장소 기준입니다. 이 저장소는 참조용으로만 클론하고, 실제 작업은 dictionary-app 저장소 자체에서 진행합니다.

기술 스택

프레임워크

React 19 (React Compiler 활성화)

빌드 도구

Vite (Rolldown)

Chakra UI v3 + Emotion

상태/통신

TanStack Query · React Router · React Hook Form + Zod · Zustand · axios

환경 설정

패키지 매니저는 pnpm만 사용한다(npm/yarn 금지, pnpm-lock.yaml 기준).
Terminal window
```
pnpm install
```
dictionary-api(백엔드)가 형제 디렉토리(../dictionary-api)에 클론되어 있어야 API 연동이 된다.
백엔드 API 주소를 .env에 설정한다(VITE_APP_API_URL). 로컬 백엔드 기본 포트는 8080.
개발 서버 실행:
Terminal window
```
pnpm dev
```

자주 쓰는 명령

명령	설명
`pnpm dev`	개발 서버 실행
`pnpm build`	타입체크(`tsc -b`) + 프로덕션 빌드
`pnpm lint`	oxlint 실행
`pnpm preview`	빌드 결과 미리보기
`pnpm gen:api-types`	백엔드 OpenAPI 스펙(`localhost:8080/v3/api-docs`)에서 `src/types/schema.ts` 생성

인증

세션 쿠키 기반 인증이다(JWT 아님). axios가 withCredentials: true + VITE_APP_API_URL(baseURL) 조합으로 세션 쿠키를 실어 호출한다(src/hooks/useAxiosInterceptor.ts 참고).

디렉토리 구조

src/
├── main.tsx / App.tsx
├── components/    # Atomic Design (atoms/molecules/organisms)
├── hooks/         # apis/queries/mutations/stores 하위 구조
├── layout/
├── pages/         # 페이지별 components/apis/queries/mutations/stores/models
├── routes/
├── theme/
├── types/
└── utils/

디렉토리 이름은 소문자 케밥 케이스(-), 언더바(_) 금지.
각 디렉토리는 index.ts로 export하고, 외부에서는 @/{디렉토리} 최상위 배럴로만 import한다(단, 같은 디렉토리 내부에서 서로 참조할 때는 배럴을 거치지 않고 상대 경로/좁은 하위 배럴을 쓴다 — 순환 참조 방지).
커스텀 훅은 소속에 따라 접미사가 붙는다: apis → Api, queries → Query, mutations → Mutation, stores → Store.

코딩 컨벤션 핵심

function 대신 화살표 함수. 이름 붙여 정의하는 함수는 암묵적 반환 대신 { return ... } 형태로 작성(인라인 콜백 제외).
export default 사용 안 함 — 정의 시 export const로 바로 export.
이벤트 핸들러는 handle 접두사(handleClick), JSX 인라인 화살표 함수 대신 이름 붙은 함수로 분리.
타입은 interface 대신 type.
스타일은 Chakra UI v3의 chakra() 팩토리로 작성(Styled{컴포넌트 이름}.ts), CSS 파일/sx/인라인 style 금지.

커밋 전 체크

husky pre-commit 훅이 lint-staged(oxlint –fix + prettier)와 pnpm run build(타입체크 포함)를 실행한다 — 훅이 실패하면 원인을 고쳐 다시 커밋한다. --no-verify로 우회하지 않는다.