[ReactJS] CRA와 Vite 프로젝트, 마이그레이션하기

리액트 프로젝트는 모두 React를 기반으로 하지만, 사용하는 개발 도구(빌드 도구)에 따라 다르다.

React 앱을 만들 때 주로 사용하는 CRA(Create React App) 과 Vite는 프로젝트를 빠르게 시작하고 실행할 수 있게 도와주는 빌드 도구(혹은 개발 환경 도구)를 말한다.
CRA는 전통적인 방식이고, Vite는 최신 방식으로 빠르고 설정이 유연하다는 장점을 가지고 있다.

 

CRA vs Vite 차이

항목	CRA (Create React App)	Vite
실행 명령어	npm start	npm run dev
설정 파일	거의 숨겨져 있음 (eject해야 수정 가능)	직접 설정 가능 (Vite config 파일 존재)
빌드 속도	느림 (웹팩 사용)	매우 빠름 (ESBuild 사용)
사용 기술	Webpack 기반	ESBuild + Rollup 기반
초기화 명령어	npx create-react-app	npm create vite@latest

 

 

---

 

 

CRA 이해하기

CRA는 Facebook(메타)이 만든 React 공식 초기화 도구이다. React 앱을 빠르게 만들 수 있도록 기본 구조와 설정을 제공한다.
내부적으로 Webpack과 Babel을 사용한다.

my-app/
├── public/
│   └── index.html
├── src/
│   ├── App.js
│   └── index.js
├── package.json

CRA 작동 방식

npm start 시 webpack-dev-server를 실행한다. Babel이 최신 JS 문법을 옛 브라우저에서도 작동하게 변환한다. 번들링은 Webpack이 담당하는데 결과물이 무겁다는 단점이 있다.

 

장점

• 안정적이고 오래되었다.
• 설정이 자동이라 초보자에게 쉽다.
• 플러그인 없이 바로 시작 가능하다.

 

단점

• 느리다. 특히 큰 프로젝트일수록 느리다.
• 설정을 수정하려면 eject 해야 해서 복잡해진다.
• Webpack 기반이라 초기 로딩과 번들링 속도가 느리다.

 

---

 

 

Vite 이해하기

Vite는 Vue.js의 창시자인 Evan You가 만든 도구로, "Vite"는 프랑스어로 '빠름'을 의미한다. 기존의 Webpack, Parcel 같은 번들러가 전체 코드를 한번에 번들링하는 방식이라면, Vite는 개발 중에는 브라우저가 필요한 모듈만 동적으로 불러오는 모듈 기반 개발 서버 방식을 사용한다. 이 덕분에 서버를 시작하는 속도가 매우 빠르고, 변경 사항을 저장할 때도 HMR(Hot Module Replacement)이 거의 즉시 반영된다.

my-vite-app/
├── index.html
├── src/
│   ├── App.tsx
│   └── main.tsx
├── vite.config.ts
├── package.json

 

 

Vite 작동 방식

개발 중엔 ESBuild로 번들링 없이 바로 실행하기 때문에 속도가 빠르다. 배포 시엔 Rollup으로 최적화된 번들 생성한다. 설정 파일 (vite.config.ts)을 통해 유연하게 커스터마이징 가능하다.

 

장점

Vite의 가장 큰 장점은 빠른 개발 환경과 간편한 설정이다. React, Vue, Svelte 등 다양한 프레임워크를 쉽게 설정할 수 있으며, TypeScript, JSX, CSS 모듈, PostCSS, Sass 등도 기본적으로 지원한다. 프로젝트를 시작할 때 npm create vite@latest 명령어 하나로 필요한 설정이 자동 구성되기 때문에, 복잡한 Webpack 설정 없이도 개발을 바로 시작할 수 있다.

• 매우 빠르다. 특히 개발 서버 기동 속도가 빠르다.
• 설정이 유연하고 모던하다.
• 모듈 단위 HMR(Hot Module Replacement)이 즉시 반영된다.

 

단점

Vite는 최신 브라우저의 ESM(ES Modules)을 기반으로 하기 때문에 구형 브라우저 지원에는 한계가 있어 별도의 폴리필 설정이 필요할 수 있다. 또한, 프로젝트 규모가 커지거나 복잡한 구성(예: SSR, 마이크로 프론트엔드, 커스텀 번들링 설정 등)이 필요한 경우, Webpack보다 생태계와 도구 지원이 제한적일 수 있다. Rollup 기반 빌드 시스템도 일부 라이브러리나 플러그인과의 호환성 문제가 발생할 수 있으며, Vite 자체가 비교적 최근에 등장한 도구인 만큼, 모든 상황에서 안정적인 선택은 아닐 수 있다.

• 비교적 최근 도구라서 구형 브라우저나 환경에선 호환성 이슈가 있을 수 있다.
• CRA에 비해 자료나 튜토리얼이 상대적으로 적다.(요즘은 많이 좋아졌음).

 

---

 

 

CRA → Vite 마이그레이션하기

1. 현재 CRA 프로젝트 백업
먼저 기존 프로젝트 폴더를 복사해 백업한다. (실수해도 되돌릴 수 있어야 함)

 

2.CRA 관련 의존성 삭제

npm uninstall react-scripts

또는 package.json에서 다음을 수동 삭제한다.

"react-scripts"
"web-vitals"
"@testing-library/*" 등 CRA 기본 포함 라이브러리들 (선택)

 

 

3. Vite 관련 패키지 설치

npm install --save-dev vite
npm install react react-dom

그리고 Vite가 TypeScript 프로젝트면 아래와 같이 실행하여 설치를 진행한다.

npm install --save-dev @vitejs/plugin-react

 

 

4. Vite 설정 파일 추가
루트에 vite.config.js 또는 vite.config.ts을 생성한다.

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000
  }
})

 

 

5. index.html 파일 이동 및 수정

CRA는 public/index.html에 있지만, Vite는 프로젝트 루트(./)에 index.html이 있어야 한다.
public/index.html을 프로젝트 루트로 복사하고 다음 부분을 Vite 방식으로 수정한다.

<!-- CRA 방식 -->
<div id="root"></div>

<!-- Vite 방식 -->
<div id="root"></div>
<script type="module" src="/src/main.jsx"></script>

 

 

6. src/index.js → src/main.jsx (또는 main.tsx)
CRA에서는 src/index.js가 엔트리인데 Vite에서는 src/main.jsx 또는 main.tsx가 일반적이다.

// src/main.jsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)

7. package.json 스크립트 변경

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

8. 퍼블릭 파일 이동
CRA의 public 폴더 안에 있는 이미지나 favicon, robots.txt 등은 Vite에서도 그대로 public 폴더에 넣으면 자동 복사된다.
(단, HTML 내부 참조는 /이미지.png처럼 절대 경로로 써야 한다.)

 

9. 기타: 환경변수 이름 수정
CRA는 REACT_APP_ 접두사가 필요하지만 Vite는 VITE_로 바뀐다.

JS/TS 코드에서는 import.meta.env.VITE_API_URL로 접근해야 한다.

# CRA
REACT_APP_API_URL=https://api.example.com

# Vite
VITE_API_URL=https://api.example.com

 

 

10. 실행 테스트
실행에 성공하면 Vite 개발 서버가 뜬다.

npm run dev

 

 

11. 추가 고려사항

• 이미지 및 정적 파일 : CRA에서는 public 폴더를 사용했지만, Vite에서는 public/ 폴더를 루트에 두면 자동 처리된다.
• 라우팅 (React Router 등) : BrowserRouter 사용 시 Vite에 HTML5 히스토리 모드를 위한 설정이 필요할 수 있다.
• 테스트 도구 (Jest 등) : Vite에서는 Vitest 사용을 고려해본다.