diff --git a/front/.env.sample b/front/.env.sample new file mode 100644 index 0000000..9cba6db --- /dev/null +++ b/front/.env.sample @@ -0,0 +1,11 @@ +# 환경 변수 템플릿 (git 에 커밋되는 유일한 env 파일) +# 새 환경을 세팅할 때 이 파일을 복사해서 .env.local / .env.dev / .env.prod 를 만든다. +# +# 주의: 클라이언트(브라우저) 번들에 노출되는 변수는 반드시 VITE_ 접두사를 붙여야 한다. +# 접두사 없는 변수는 빌드에 포함되지 않는다 (서버 비밀값은 여기 두지 말 것). + +# 현재 실행 환경 식별용 (local | dev | prod) +VITE_APP_ENV=local + +# 백엔드 API 베이스 URL (negosium 백엔드 기본 포트 9300) +VITE_API_BASE_URL=http://localhost:9300 diff --git a/front/.gitignore b/front/.gitignore index a547bf3..7cd12e4 100644 --- a/front/.gitignore +++ b/front/.gitignore @@ -12,6 +12,11 @@ dist dist-ssr *.local +# env (실제 env 파일은 무시하고 .env.sample 만 커밋) +.env +.env.* +!.env.sample + # Editor directories and files .vscode/* !.vscode/extensions.json diff --git a/front/README.md b/front/README.md index 7dbf7eb..eadeeae 100644 --- a/front/README.md +++ b/front/README.md @@ -1,73 +1,66 @@ -# React + TypeScript + Vite +# Negosium Front -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +React + TypeScript + Vite 기반 프론트엔드. -Currently, two official plugins are available: +## 기술 스택 -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +- **빌드/런타임**: Vite 8, React 19, TypeScript 6 +- **상태/데이터**: TanStack Query(서버 상태), Zustand(클라이언트 상태) +- **HTTP**: axios +- **에디터**: Slate (`slate` / `slate-react` / `slate-history`) +- **스타일**: Tailwind CSS v4 (`@tailwindcss/vite`) +- **경로 alias**: `@/*` → `src/*` -## React Compiler +## 요구 사항 -The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). +- Node.js `20.19+` 또는 `22.12+` (Vite 8 요구 사항, 개발은 24.x 기준) +- npm -## Expanding the ESLint configuration +## 로컬 세팅 -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: +```bash +# 1. 프로젝트로 이동 +cd front -```js -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... +# 2. 의존성 설치 +npm install - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, +# 3. env 파일 준비 (.env.sample 복사 후 값 채우기) +cp .env.sample .env.local - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +# 4. 로컬 개발 서버 실행 (기본 http://localhost:5173) +npm run dev ``` -You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: +> 백엔드 API 는 negosium 백엔드(기본 `http://localhost:9300`)를 바라본다. `.env.local` 의 `VITE_API_BASE_URL` 로 조정한다. -```js -// eslint.config.js -import reactX from 'eslint-plugin-react-x' -import reactDom from 'eslint-plugin-react-dom' +## 환경 변수 (.env) -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs['recommended-typescript'], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +Vite 의 mode 기능으로 환경별 env 파일을 매핑한다. 클라이언트 번들에 노출되는 변수는 반드시 `VITE_` 접두사를 붙인다. + +| 파일 | mode | 용도 | git | +| --- | --- | --- | --- | +| `.env.sample` | - | 템플릿 (키 목록 공유용) | ✅ 커밋 | +| `.env.local` | `local` | 로컬 개발 | 🚫 ignore | +| `.env.dev` | `dev` | 개발 서버 | 🚫 ignore | +| `.env.prod` | `prod` | 운영 | 🚫 ignore | + +새 환경 세팅 시 `.env.sample` 을 복사해 환경별 파일을 만들고 값을 채운다. 코드에서는 `import.meta.env.VITE_API_BASE_URL` 처럼 접근한다. + +> 참고: Vite 는 mode 와 무관하게 `.env.local` 을 항상 함께 로드한다(개인 로컬 오버라이드 용도). 우선순위는 `.env.[mode]` > `.env.local` > `.env` 이므로, 각 env 파일에 **동일한 키 집합**을 유지하면 mode 파일 값이 항상 이긴다. 특정 mode 에만 있어야 할 키를 `.env.local` 에 두면 다른 mode 로 새어 들어갈 수 있으니 주의. + +## 실행 / 빌드 + +`--mode ` 으로 위 표의 env 파일이 선택된다. + +```bash +npm run dev # 로컬 개발 서버 (mode: local → .env.local) +npm run dev:dev # 개발 서버를 dev 환경 변수로 실행 (mode: dev → .env.dev) + +npm run build # 운영 빌드 (mode: prod → .env.prod), build:prod 와 동일 +npm run build:dev # 개발 빌드 (mode: dev → .env.dev) +npm run build:prod # 운영 빌드 (mode: prod → .env.prod) + +npm run preview # 직전 빌드 결과 로컬 미리보기 +npm run lint # ESLint ``` diff --git a/front/package.json b/front/package.json index 15c3db0..00f05d0 100644 --- a/front/package.json +++ b/front/package.json @@ -4,10 +4,13 @@ "version": "0.0.0", "type": "module", "scripts": { - "dev": "vite", - "build": "tsc -b && vite build", - "lint": "eslint .", - "preview": "vite preview" + "dev": "vite --mode local", + "dev:dev": "vite --mode dev", + "build": "tsc -b && vite build --mode prod", + "build:dev": "tsc -b && vite build --mode dev", + "build:prod": "tsc -b && vite build --mode prod", + "preview": "vite preview", + "lint": "eslint ." }, "dependencies": { "@tanstack/react-query": "^5.101.0",