1. 설치 방법 & 폴더 구성(Vite 기준)

Tech Note — React 1. 설치 방법 & 폴더 구성 (Vite 기준)

Tech NoteReact1화 · 2025-12

목차

1. 전제: Node.js 버전과 패키지 매니저
2. Vite로 React 프로젝트 생성
3. 폴더/파일 구조(실무 관점)
4. 개발/빌드/프리뷰 기본 명령
5. 배포 산출물(dist)과 “정적 호스팅” 감각
6. References

0) 전제: Node.js 버전과 패키지 매니저

2025년 기준, Vite는 Node.js 20.19+ 또는 22.12+를 요구한다. (템플릿에 따라 더 높은 버전이 필요할 수도 있음)

운영 관점 추천: Node는 LTS 라인을 쓰고, 프로젝트별로 버전을 “고정”하는 습관을 들이는 게 좋다. (nvm / fnm / volta 등 버전 매니저 사용 권장)

# 설치 확인
node -v
npm -v

# (선택) 패키지 매니저: npm / pnpm / yarn 중 하나를 팀 표준으로 고정

1) Vite로 React 프로젝트 생성

React 단독 SPA를 가장 빠르게 시작하는 조합 중 하나가 Vite다.

# 1) 프로젝트 생성
npm create vite@latest my-app

# 2) 템플릿 선택 예:
#   - React
#   - React + TypeScript

cd my-app
npm install
npm run dev

2) 폴더/파일 구조(실무 관점)

경로	의미(운영 관점)
src/	실제 앱 코드. 컴포넌트/라우트/훅/유틸을 여기서 정리
public/	빌드 파이프라인을 거치지 않고 그대로 배포되는 정적 파일
vite.config.*	빌드/개발 서버 설정. 프록시/별칭(alias)/빌드 옵션 등
.env*	환경 변수(빌드 시점 주입). 비밀정보는 절대 넣지 않는 게 원칙
dist/	빌드 결과물. 배포 대상(정적 호스팅)
package-lock.json / pnpm-lock.yaml	락 파일. “재현 가능한 빌드”의 핵심

3) 개발/빌드/프리뷰 기본 명령

# 개발 서버(핫리로드)
npm run dev

# 프로덕션 빌드
npm run build

# 빌드 결과물 로컬 프리뷰(배포 전 확인)
npm run preview

4) 배포 산출물(dist)과 “정적 호스팅” 감각

React(Vite) SPA는 빌드하면 dist/ 아래에 HTML/CSS/JS가 만들어지고, 이를 Nginx 같은 웹서버가 정적 파일로 서빙하는 형태가 일반적이다.

“React를 배포한다”는 말은, 보통 “dist를 웹서버에 올린다”로 이해하면 된다. 인증/권한/데이터는 별도 API(예: Node/Go/Python)가 담당.

References

• Vite 공식 가이드(한국어) — 시작하기 / Node 요구사항
• create-vite (npm)
• Vite 7 공지 — Node 지원 범위 변경
• Node.js Release WG (LTS/Current 정책)

다음 글: Tech Note — React 2. 실무 옵션/설정(라우팅/환경변수/보안 기본)