프론트엔드 환경 · 구성

프론트엔드는 React 19 + TypeScript, 빌드 도구는 Vite, 패키지 매니저는 pnpm입니다. 실제 package.json·vite.config.ts·tsconfig.json 기준으로 정리했어요.

실행 스크립트

# package.json "scripts"
pnpm dev       # 개발 서버 (Vite, 기본 :5173)
pnpm build     # 프로덕션 빌드 (vite build)
pnpm preview   # 빌드 결과 미리보기
pnpm serve     # build + preview
pnpm test      # 테스트 (jest)

설치된 라이브러리 (런타임 의존성)

화면을 만들고 동작시키는 데 실제로 쓰이는 패키지들입니다(역할별 분류).

역할	패키지
코어	`react` 19.2.3 · `react-dom` 19.2.3
라우팅 · 서버상태 · 테이블	`@tanstack/react-router` · `@tanstack/react-query` · `@tanstack/react-table`
클라이언트 상태	`zustand` · `@preact/signals-react`
HTTP 요청	`ky`
폼 · 검증	`react-hook-form` · `@hookform/resolvers` · `zod` · `zod-i18n-map`
UI 컴포넌트	`@radix-ui/react-*`(다수) · `shadcn` · `@base-ui/react` · `cmdk` · `sonner`(토스트) · `next-themes`
아이콘	`lucide-react` · `@hugeicons/react`
스타일	`tailwindcss` 4 — 빌드 시 적용(개발 의존성, `@tailwindcss/vite` 플러그인)
드래그&드롭	`@dnd-kit/core` · `/sortable` · `/utilities`
파일 · 표	`react-dropzone` · `exceljs` · `xlsx`
차트	`recharts`
날짜 · 숫자 · 유틸	`date-fns` · `numbro` · `lodash-es`
국제화 · URL 상태	`i18next` · `nuqs`
레거시 웹컴포넌트 호환	`@polymer/polymer` · `lit` · `construct-style-sheets-polyfill`

개발 의존성 (빌드 · 품질 도구)

역할	패키지
언어 · 빌드	`typescript` 5.4.5 · `vite` 5.3.3 · `@vitejs/plugin-react` · `@babel/preset-react`
Vite 플러그인	`@tanstack/router-vite-plugin` · `@tailwindcss/vite` · `@preact/signals-react-transform` · `vite-plugin-checker`
스타일 유틸	`class-variance-authority` · `clsx` · `tailwind-merge` · `tw-animate-css` · `postcss`
테스트	`jest` · `ts-jest` · `@types/jest`
타입 정의	`@types/react` · `@types/react-dom` · `@types/node` (참고: `@types/lodash-es`는 런타임 dependencies에 위치)
PWA · 번들분석	`workbox-*` · `rollup-plugin-visualizer` · `rollup-plugin-brotli`

참고

런타임 약 60개 + 개발 약 35개입니다. 위 표는 역할별 대표만 추렸고, 전체 정확한 버전은 study-frontend/package.json 에 있습니다.

Vite 설정 (vite.config.ts)

빌드/개발 서버 설정입니다. 핵심은 플러그인, 경로 별칭, API 프록시예요.

export default defineConfig({
  plugins: [
    react({ babel: { plugins: [["module:@preact/signals-react-transform"]] } }),
    TanStackRouterVite(),   // 파일 기반 라우팅 자동 생성
    tailwindcss(),          // Tailwind 4
  ],
  resolve: {
    alias: { "@": path.resolve(__dirname, "./src") },   // import "@/..." = src 기준
  },
  server: {
    watch: { ignored: ["**/routeTree.gen.ts"] },
    proxy: {
      "/api": { target: "http://localhost:8084", changeOrigin: true },  // 백엔드로 전달
    },
  },
})

프록시가 하는 일

개발 중 프론트가 /api/... 를 부르면 Vite가 백엔드(:8084)로 넘겨줍니다. 같은 출처처럼 보여 CORS^? 문제가 없어요. 자세한 흐름은 연동 1장.

TypeScript 설정 (tsconfig.json)

{
  "compilerOptions": {
    "jsx": "react-jsx",        // JSX를 React 17+ 방식으로 컴파일
    "target": "es2022",
    "module": "esNext",
    "strict": true,            // 엄격한 타입 검사
    "baseUrl": "src",
    "paths": { "@/*": ["*"] }, // "@/components/.." = src/components/..
    "esModuleInterop": true
  },
  "include": ["src/**/*", "types.d.ts"]
}

폴더 구조 (src)

src/
├── app/        # 앱 설정, 인증(auth), providers
├── components/ # 재사용 UI (ui/ = shadcn)
├── features/   # 도메인 컴포넌트(회사·상품·주문 등)
├── hooks/      # 공통 커스텀 훅
├── i18n/       # 다국어(국제화)
├── lib/        # api(ky), jwt, format, 유틸
├── pages/      # 화면(라우트와 1:1)
├── routes/     # TanStack Router 파일 기반 라우트
├── service/    # endpoint 클라이언트 + 타입
├── stores/     # Zustand (auth, permission)
├── types/      # 공통 타입
└── views/      # 공통 뷰