빌드 도구난이도 보통⏱ 1~3시간
Create React App에서 Vite로 마이그레이션
Create React App→Vite
요약: react-scripts를 Vite로 교체하면 dev 서버 기동·HMR이 수 배 빨라집니다. index.html 위치와 환경변수 접두사(REACT_APP_ → VITE_)만 주의하면 대부분 그대로 동작합니다.
왜 옮기나
- CRA(react-scripts)는 2023년 이후 사실상 유지보수 중단 상태이고 dev 기동이 느립니다.
- Vite는 esbuild 기반으로 콜드 스타트·HMR이 훨씬 빠르고 설정이 가볍습니다.
- React 공식 문서도 신규 프로젝트에 CRA 대신 Vite 계열을 권장합니다.
전제 — 현재 상태
react-scripts 기반 CRA 프로젝트, public/index.html, src/index.js 진입점, REACT_APP_ 환경변수 사용.
마이그레이션 단계
1
Vite와 플러그인 설치
react-scripts를 제거하고 Vite와 React 플러그인을 설치합니다.
npm uninstall react-scripts
npm install -D vite @vitejs/plugin-react2
index.html을 루트로 이동
Vite는 index.html을 프로젝트 루트에서 진입점으로 씁니다. public/index.html을 루트로 옮기고 %PUBLIC_URL% 같은 CRA 토큰을 제거한 뒤 <script type="module" src="/src/index.jsx">를 추가합니다.
3
vite.config.js 작성
React 플러그인과 dev 포트(CRA 기본 3000)를 설정합니다.
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({ plugins: [react()], server: { port: 3000 } })4
환경변수 접두사 변경
CRA의 process.env.REACT_APP_*는 Vite에서 import.meta.env.VITE_*로 바뀝니다. .env의 접두사와 코드 참조를 모두 교체합니다.
# .env
VITE_API_URL=https://api.example.com
// 코드
import.meta.env.VITE_API_URL5
package.json 스크립트 교체
start/build/test 스크립트를 Vite 명령으로 바꿉니다.
"dev": "vite",
"build": "vite build",
"preview": "vite preview"⚠️ 막히는 케이스 · 함정
- JSX가 든 파일은 확장자를 .jsx/.tsx로 바꿔야 esbuild가 처리합니다(.js 안의 JSX는 에러).
- SVG를 컴포넌트로 import 했다면 vite-plugin-svgr가 필요합니다.
- process.env를 런타임에서 직접 참조하던 코드는 import.meta.env로 모두 교체해야 합니다.
- jest 기반 테스트는 Vitest로 함께 옮기는 것이 자연스럽습니다.
✅ 검증: npm run dev로 dev 서버가 뜨고 HMR이 동작하는지, npm run build && npm run preview로 프로덕션 번들이 정상 렌더되는지 확인합니다.
ViteCreate React AppCRAReact빌드도구