Vite React Frontend Template

실무에서 반복되는 구조를 바로 가져다 쓸 수 있도록 만든 Vite + React + TypeScript 템플릿이다.

Defaults

• feature-first 구조
• react-router-dom 기본 포함
• src/pages/**/page.tsx 기반 자동 라우팅
• 공통 request 코어 + 클라이언트 wrapper 분리
• TanStack Query 중심 서버 상태 관리
• Zustand는 전역 UI 상태에만 사용
• React Hook Form + Zod 예제는 CRUD feature 생성 시 추가
• 날짜, 포맷팅, query string, 에러 처리 같은 공통 로직 분리

Quick Start

npm install
cp .env.example .env.local
npm run dev

필수 환경 변수:

VITE_API_BASE_URL=http://localhost:4000

• 클라이언트 요청은 기본적으로 VITE_API_BASE_URL을 사용한다.
• feature API 함수는 features/<name>/api 아래에 둔다.

Structure

src/
  app/
  pages/
  features/
  shared/
    api/
    auth/
    config/
    error/
    lib/
    query/
    routes/
    ui/
    utils/

• app
  • 앱 엔트리, router, provider, 공통 frame을 둔다.
• pages
  • route component를 둔다. src/pages/**/page.tsx는 자동으로 React Router 경로가 된다.
• features
  • 특정 도메인에서만 쓰는 API, hook, component, lib를 둔다.
• shared
  • 두 개 이상 feature 또는 앱 전역에서 재사용하는 공통 코드만 둔다.

라우트 예시:

• src/pages/index/page.tsx -> /
• src/pages/login/page.tsx -> /login
• src/pages/products/page.tsx -> /products
• src/pages/products/new/page.tsx -> /products/new

Request And Error Flow

요청 함수 선택 기준:

• 일반 요청: requestClient
• 인증 쿠키 포함 요청: requestClientAuth

기준:

• request.ts는 공통 타입과 실행 함수 정의를 두고, 실제 사용은 wrapper를 통해 한다.
• 상대 경로 요청은 VITE_API_BASE_URL을 기준으로 실행된다.
• request는 정규화된 AppError를 throw한다.

예시:

import { requestClient } from '@/shared/api/request.client';

export function getProducts(search?: string) {
  return requestClient<Product[]>({
    method: 'GET',
    url: '/products',
    params: { search },
  });
}

옵션 예제:

• src/shared/error/handle-app-error.client.ts
• src/shared/auth/auth-error-listener.tsx
• src/shared/ui/global-modal.tsx
• 기본 템플릿에서는 연결하지 않으며, 필요하면 src/app/providers.tsx, src/app/frame.tsx에서 수동으로 연결한다.

Scripts

npm run dev
npm run build
npm run preview
npm run lint
npm run lint:fix
npm run format
npm run format:check
npm run pack:dry-run
npm run release:check
npm run create:feature -- products
npm run create:feature:crud -- products

Create Feature

npm run create:feature -- products

생성 대상:

• src/features/<name>/api/
• src/features/<name>/components/
• src/features/<name>/hooks/
• src/features/<name>/lib/
• src/pages/<name>/page.tsx

주의:

• 최소 폴더 구조와 route page만 만든다.
• route는 src/pages/**/page.tsx 규칙으로 자동 연결된다.
• CRUD 예제가 필요하면 아래 명령을 사용한다.

npm run create:feature:crud -- products

CRUD 예시 생성 대상:

• src/features/<name>/api
• src/features/<name>/components
• src/features/<name>/hooks
• src/features/<name>/lib
• src/pages/<name>/page.tsx
• src/pages/<name>/new/page.tsx

주의:

• 생성된 API 함수는 외부 백엔드 연동을 전제로 한다.
• same-origin mock route는 생성하지 않는다.
• routePaths는 자동 병합하지 않는다.
• 필요하면 생성 후 src/shared/routes/route-paths.ts에 직접 추가한다.

관련 스크립트:

• scripts/create-app.mjs
• scripts/create-feature.mjs
• scripts/create-feature-crud.mjs

Coding Defaults

• 앱 내부 타입 선언은 기본적으로 .ts / .tsx에서 type을 우선 사용한다.
• interface는 declaration merging이나 외부 타입 확장처럼 확장 계약이 필요할 때만 사용한다.
• query key는 feature별 파일에서 관리하고, GET은 query, POST/PUT/PATCH/DELETE는 mutation으로 분리한다.
• URL로 표현 가능한 상태는 URL에 두고, 전역 store는 여러 컴포넌트가 함께 알아야 하는 UI 상태에만 사용한다.
• 날짜와 숫자 포맷팅은 공통 함수로 관리한다.
• 클릭 가능한 요소는 button, 이동은 Link를 사용하고, input은 label과 연결한다.

Create App

배포 전에 템플릿 로컬 검증이 필요하면 이 저장소에서 바로 실행할 수 있다.

node ./scripts/create-app.mjs my-app

commitlint까지 같이 확인하고 싶으면:

node ./scripts/create-app.mjs my-app --with-commitlint

스타일 없이 시작하는 버전으로 확인하고 싶으면:

node ./scripts/create-app.mjs my-app --no-style

패키지를 npm에 배포한 뒤에는 아래처럼 사용할 수 있다.

npm create react-0to1@latest my-app

또는:

bun create react-0to1 my-app

기본 실행 시에는 create-vite의 원래 인터랙션이 그대로 열린다.

이 템플릿은 React 계열 Vite 템플릿만 지원한다.

• 예: react-ts, react-compiler-ts
• vue, svelte, solid 같은 비-React 템플릿을 고르면 생성 결과를 정리한 뒤 안내 메시지와 함께 중단한다.

인터랙션 없이 바로 만들고 싶으면:

npm create react-0to1@latest my-app -- --template react-ts

React Compiler 템플릿을 바로 쓰고 싶으면:

npm create react-0to1@latest my-app -- --template react-compiler-ts

배포 후 commitlint까지 같이 넣고 싶으면:

npm create react-0to1@latest my-app -- --with-commitlint

스타일 파일 없이 시작하고 싶으면:

npm create react-0to1@latest my-app -- --no-style

--with-commitlint를 켜면 commit-msg hook과 commitlint 설정이 추가되고, feat: 내용 같은 Conventional Commits 형식을 검사한다. --no-style을 켜면 @tailwindcss/vite, tailwindcss, 전역 CSS import를 제외하고 기본 화면과 feature 스캐폴드도 스타일 없이 생성한다.

Release Flow

첫 공개 릴리스 전에는 아래 순서를 권장한다.

1. npm run release:check
2. npm publish
3. npm view create-react-0to1 version
4. 배포 확인 후 README의 npm create react-0to1@latest my-app 예시를 사용한다.

버전을 올려서 배포할 때는 필요 시 먼저 package.json과 package-lock.json의 버전을 함께 갱신한다.

이 템플릿은 TypeScript + React Router + ESLint + Vite 전제를 가진다. Husky는 기본 설치하며, pre-commit에서 lint만 실행한다.