[React] CRA(Webpack)에서 Vite로 마이그레이션 과정

[React] CRA(Webpack)에서 Vite로 마이그레이션 과정Frontend/React2025. 3. 11. 14:53@동혁이

Table of Contents

CRA(Create-React-App)에서 Vite로 마이그레이션 과정

1. 들어가며

지금까지 협업 프로젝트와 토이 프로젝트를 진행하면서 항상 Webpack 번들러를 사용해왔다.

하지만 프로젝트 규모가 커질수록 개발 서버 구동 시간과 빌드 시간이 눈에 띄게 느려지는 것을 경험했었고 마음속에 답답함이 있었다.

이러한 성능 이슈를 해결하고자, 이번 토이 프로젝트에서는 더 빠른 번들러로 알려진 Vite로 마이그레이션을 진행해보고 싶었고 그 경험과 과정을 공유하고자 포스팅을 하게 되었다.

2. CRA(Webpack) VS Vite(rollup, esbuild)

CRA는 Webpack을 기반으로 구성되어 있고, Vite는 rollup, esbuild를 기반으로 구성되어 있다.

Webpack은 프론트엔드 공부를 하는 사람이라면 자주 본 단어이다.

Webpack, rollup, esbuild의 역할은 번들러 이다.

번들러 인거는 알겠는데 무슨 기능을 할까?

여러 개의 파일들을 하나의 파일로 묶어주는 도구
더 작은 용량, 더 최적화된 리소스를 제공
사용되지 않는 코드를 분석해서 제거

표를 통해 정리해보면 아래와 같다

특징	CRA	Vite
빌드 도구	Webpack	Rollup
개발 서버	Webpack Dev Server	Native ESM + esbuild
초기 설정	미리 구성됨	최소한의 설정
개발 서버 시작 속도	느림	매우 빠름
커스터마이징	eject 필요 or 복잡	간단 유연
SSR	추가 설정 필요	기본 지원
레거시 브라우저 지원	좋음	제한적 (추가 설정 필요)

3. 마이그레이션 과정

기본적인 CRA 프로젝트 구조이다.

3.1 Vite, Vite React 플러그인 설치

yarn add -D vite @vitejs/plugin-react

3.2 Typescript 설치

yarn add -D typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin

- 3.1, 3.2 까지 진행 후 node_modules 파일 삭제 및 재설치

3.3 package.json 수정

- script 수정

"scripts": {
    "start": "vite",
    "build": "tsc && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },

3.4 vite.config.ts 추가

- 실제로는 더 많은 설정이 추가 될 수 있다 - svg, md, 빌드 파일 해시, 폴리필 등 (참고)

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});

3.5 tsconfig.json 추가

- 기존 설정에 타입스크립트가 vite를 인식하도록 추가

{
  "compilerOptions": {
    "types": ["vite/client"],
    / ... /
  },
  / ... /
}

3.6 tsconfig.node.json 추가

{
  "compilerOptions": {
    / ... /
  },
  "include": ["vite.config.ts"]
}

3.7 vite-env.d.ts

- src 내부에 vite.env.d.ts 파일 추가

/// <reference types="vite/client" />

3.8 public 폴더 내에 있는 index.html 파일 root로 이동

- head 내부에 있는 %PUBLIC_URL% 제거

// 기존
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />

// 수정
<link rel="icon" href="/favicon.ico" />

- body 내부에 추가

<body>
  <div id="root"></div>
  <script type="module" src="/src/index.tsx"></script>
</body>

3.9 기존 CRA js 확장자 tsx로 변경

- CRA에서 .js 였던 JSX 파일을 .tsx 확장자로 변경한다.

4. 트러블 슈팅

Vite 마이그레이션 설정을 모두 끝내고 개발 서버를 열어보니 아래와 같은 오류를 만났다.

1. The CJS build of Vite's Node API is deprecated. ...

https://vite.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated

Vite

Next Generation Frontend Tooling

vite.dev

공식 문서를 찾아보니 해답이 나와 있었다.

시도한 것 / 해결 방법

위 링크를 참고하여 쉽게 해결할 수 있었다.

해당 프로젝트에서 CommonJS (CJS) 가 아닌 ECMAScript Modules (ESM) 문법을 사용하고 있었기 때문에 package.json 파일에 "type": "module" 을 추가하여 default 를 ESM으로 설정하였다.

(참고) ESM이 아닌 CJS를 사용하는 경우 확장자를 .cjs 로 명시하면 된다.

- package.json에 추가

5. 추가 코드 개선

1. 절대 경로 -> 상대 경로

기존 코드 문제점

- 위 사진과 같이 depth가 더 깊어질수록 코드의 가독성이 매우 떨어지게 된다.

1.1 개선

- vite.config.ts alias 추가

- tsconfig.json paths 추가

절대 경로 관련 코드를 추가 해줬다.

이젠 depth와 상관없이 코드가 깔끔해졌다.

2. 불필요한 라이브러리 제거

- CRA, testing 관련 라이브러리 제거

yarn remove
////////////////////
react-scripts
web-vitals
@testing-library/dom
@testing-library/jest-dom
@testing-library/react
@testing-library/user-event
////////////////////

6. 성능 비교 및 개선 결과

개선 결과는 아래 표와 같습니다.

측정 항목	CRA(Webpack)	Vite(rollup, esbuild)	개선율
개발 환경 구동 시간	약 12초	약 110ms	약 99.17%
빌드 소요 시간	약 10초	약 3.5초	약 65%

@동혁이 :: Eun_Frontend

프론트엔드 공부일지 입니다.

포스팅이 좋았다면 "좋아요❤️" 또는 "구독👍🏻" 해주세요!