이 문서는 프로젝트에 포함된 주요 기술이 어떤 역할을 하는지 설명합니다.
| 기술 |
역할 |
| Node.js 24.19.0 |
로컬 개발, 빌드, 테스트 실행 런타임 |
| pnpm 11.22.0 |
패키지 설치와 script 실행 |
| mise |
Node 버전과 반복 task 실행 진입점 관리 |
| Vite |
개발 서버, HMR, production bundle 생성 |
| TypeScript |
정적 타입 검사와 editor tooling |
| 기술 |
역할 |
| React 19 |
UI component와 client rendering 기반 |
| Tailwind CSS v4 |
utility-first styling과 dark variant 구성 |
| lucide-react |
헤더, 버튼 등에 쓰는 아이콘 |
| Radix UI Dialog |
접근성 있는 Dialog primitive |
| class-variance-authority |
Button, Badge 같은 variant 기반 스타일 구성 |
| clsx, tailwind-merge |
조건부 class 조합과 Tailwind class 충돌 정리 |
| 기술 |
역할 |
| TanStack Router |
file route 기반 라우팅, route params, type-safe route tree |
@tanstack/router-plugin |
Vite build/dev 시 route tree 생성 보조 |
@tanstack/router-cli |
pnpm generate-routes에서 route tree 생성 |
라우트 파일은 src/routes에 있고, 생성 파일은 src/routeTree.gen.ts입니다.
beforeLoad + 라우터 context로 보호 라우트(인증 가드)를 구성하고, 플러그인의 autoCodeSplitting으로 라우트별 코드 스플리팅을 적용합니다.
| 기술 |
역할 |
| TanStack Query |
서버 데이터 fetch, cache, loading/error state, mutation invalidation |
| Zustand |
UI(테마/밀도), 인증, 알림(toast) 같은 client 상태 |
| MSW |
개발/테스트 환경에서 mock API 제공 |
서버 데이터와 클라이언트 상태를 분리하는 것이 이 템플릿의 핵심 기준입니다.
Zustand store는 용도별로 나뉩니다: ui-store(테마/밀도 preference는 localStorage key react-sample-ui),
auth-store(토큰/사용자, key react-sample-auth), toast-store(전역 알림, 비영속).
| 기술 |
역할 |
| React Hook Form |
form field 등록, submit, field error 관리 |
| Zod |
form input schema와 runtime validation |
@hookform/resolvers |
Zod schema를 React Hook Form resolver로 연결 |
프로젝트 생성 Dialog와 로그인 폼(SignInPage)에서 form state, validation, submit 흐름을 확인할 수 있습니다.
| 기술 |
역할 |
| ESLint |
TypeScript, React Hooks, React Refresh, Testing Library 규칙 검사 |
| Prettier |
코드 포맷과 Tailwind class 정렬 |
| Vitest |
unit/component/integration test runner |
| Testing Library |
사용자 관점 DOM 테스트 |
| jsdom |
브라우저 DOM API를 테스트 환경에 제공 |
| V8 coverage |
coverage report provider |
- routing은 URL과 page 연결을 명확히 보여주기 위해 TanStack Router를 사용한다.
- 서버 상태는 직접
useEffect로 관리하지 않고 TanStack Query로 cache와 invalidation을 표현한다.
- 전역 UI preference는 Zustand로 작게 관리한다.
- API 서버가 없어도 기능 흐름을 확인할 수 있도록 MSW를 사용한다.
- form 예제는 React Hook Form과 Zod를 함께 사용해 실무에서 흔한 검증 흐름을 보여준다.
generate-routes와 watch-routes는 scripts/router-cli.mjs에서 Router CLI의 공개 ESM 진입점을 사용합니다. upstream tsr 실행 파일의 CommonJS 순환 참조 경고를 피하면서 같은 명령과 종료 코드를 유지합니다.- Router·CLI·plugin은 서로 다른 버전 번호로 릴리스됩니다. 숫자를 강제로 통일하기보다 lockfile의 core/generator 의존성과 생성·빌드를 함께 검증합니다.
vite.config.ts의 TanStack Router 플러그인 autoCodeSplitting으로 각 라우트 컴포넌트가 별도 청크로 분리되어 초기 번들이 작아집니다.