o2o-negosium-original/frontend

Negosium Front

React + TypeScript + Vite 기반 프론트엔드.

기술 스택

• 빌드/런타임: Vite 8, React 19, TypeScript 6
• 상태/데이터: TanStack Query(서버 상태), Zustand(클라이언트 상태)
• HTTP: axios
• 에디터: Slate (slate / slate-react / slate-history)
• 스타일: Tailwind CSS v4 (@tailwindcss/vite)
• 경로 alias: @/* → src/*

요구 사항

• Node.js 20.19+ 또는 22.12+ (Vite 8 요구 사항, 개발은 24.x 기준)
• npm

로컬 세팅

# 1. 프로젝트로 이동
cd front

# 2. 의존성 설치
npm install

# 3. env 파일 준비 (.env.sample 복사 후 값 채우기)
cp .env.sample .env.local

# 4. 로컬 개발 서버 실행 (기본 http://localhost:5173)
npm run dev

백엔드 API 는 negosium 백엔드(기본 http://localhost:9300)를 바라본다. .env.local 의 VITE_API_BASE_URL 로 조정한다.

환경 변수 (.env)

Vite 의 mode 기능으로 환경별 env 파일을 매핑한다. 클라이언트 번들에 노출되는 변수는 반드시 VITE_ 접두사를 붙인다.

파일	사용 시점	git
.env.sample	템플릿 (키 목록 공유용)	✅ 커밋
.env.local	로컬 개발 (npm run dev, Vite 가 자동 로드)	🚫 ignore
.env.dev	--mode dev (개발 서버)	🚫 ignore
.env.prod	--mode prod (운영)	🚫 ignore

새 환경 세팅 시 .env.sample 을 복사해 환경별 파일을 만들고 값을 채운다. 코드에서는 import.meta.env.VITE_API_BASE_URL 처럼 접근한다.

참고: Vite 8 부터 local 은 모드 이름으로 사용할 수 없다(.env.local 의 .local 접미사와 충돌). 그래서 로컬 개발은 별도 모드 없이 기본 vite(mode: development)로 실행하고, 로컬 값은 .env.local 에 둔다 — Vite 는 .env.local 을 모든 모드에서 항상 자동 로드한다(개인 로컬 오버라이드 용도). 우선순위는 .env.[mode] > .env.local > .env 이므로, 각 env 파일에 동일한 키 집합을 유지하면 mode 파일 값이 항상 이긴다. 특정 mode 에만 있어야 할 키를 .env.local 에 두면 다른 mode 로 새어 들어갈 수 있으니 주의.

실행 / 빌드

--mode <name> 으로 .env.[name] 파일이 선택된다(로컬은 모드 없이 .env.local 자동 로드).

npm run dev          # 로컬 개발 서버 (mode: development → .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