[React] CRA에서 Vite로 마이그레이션하기

Front-End/React JS 2024. 9. 11. 22:50

 

지금까지 리액트 프로젝트를 진행하면서 대부분 CRA로 생성하였다.

이전 프로젝트들의 크기 및 파일 개수는 상대적으로 많지 않았지만 1년째 진행중인 프로젝트는 파일 개수가 점점 많아지면서 규모가 커졌다.

Github Actions로 CI/CD로 설정된 상태에서 merge 될 때마다 빌드가 되고 있는 상태인데, CRA로 프로젝트를 생성하여서 규모가 커질수록 빌드 속도가 매우 오래걸리는 단점을 가졌다.

규모가 지금보다 크기 전까지는 1분전으로 빌드되던 프로젝트였다.

하지만 지금 현재는 거의 3분 가까이 시간이 소요되는 것을 확인할 수 있었다.

Vite가 CRA에 비해 빌드 속도가 압도적으로 빠르다는 것을 알고 배포까지 완료하여 업데이트 중인 프로젝트를 Vite로 마이그레이션 해보기로 결정하였다.

 

" 해당 프로젝트는 CRA, TypeScript, npm 기반의 프로젝트이다. "

 

우선 마이그레이션 방법을 알아보기에 앞서 CRA와 Vite의 차이점을 알아보고자 한다.

 

 

01. CRA(Create React App)

CRA는 React로 웹 프론트엔드 개발을 해봤다면 한 번이라도 들어봤거나 사용해봤을 것이다.

페이스북에서 개발한 공식 React 보일러플레이트 툴로, React 어플리케이션을 빠르게 생성할 수 있는 템플릿을 제공한다.

웹팩을 기본 빌드 도구로 사용하며, 설정이 필요 없이 바로 React 앱을 만들고 실행할 수 있다.

 

◼︎ 속도

  • 초기 서버 시작 속도 느림. CRA는 웹팩 기반으로 모든 파일을 번들링한 후에야 페이지가 로드된다.
  • 파일이 많아질수록, 즉 큰 프로젝트일수록 빌드 시간이 느려진다.

 

◼︎ 설정

  • CRA는 기본적으로 설정 파일을 숨기고 제공하여 초보자도 쉽게 프로젝트를 시작할 수 있다.
  • 추가 설정이나 커스터마이징을 하려면 eject 명령을 사용해야 하며, 이 작업은 되돌릴 수 없다.
  • eject 없이 복잡한 설정을 변경하는 것은 제한적이다.

 

◼︎ Less to Learn(자동 최적화)

  • React가 새로운 버전으로 업데이트되면, CRA는 자동으로 최적화를 수행하므로 별도의 코드 수정 벗이 최신 환경을 유지할 수 있다.

 

◼︎ Only One Dependency(단일 의존성 관리)

  • CRA 프로젝트는 하나의 빌드 dependency만 필요하며, CRA가 내부적으로 Webpack, Babel, ESLint 등을 관리하여 복잡한 버전 충돌을 방지한다.

 

◼︎ No Lock-In(고급 설정 가능)

  • Webpack, Babel, ESLint 등 다양한 패키지를 사용하여 기본 설정으로도 개발이 가능하지만, 고급 설정을 원할 경우 eject 명령ㅇ르 통해 설정 파일을 편집할 수 있다.

위와 같이 많은 기능들이 포함되어 있어 편하게 개발이 가능하지만, 많은 기능들이 포함되어 있기에 느릴 수 밖에 없다.

 

 

 

 

 

02. Vite

Vite는 빠른 개발 서버와 빠른 번들링을 제공하는 도구이다. 

개발 중에는 ES 모듈을 이용하고, 빌드 시에는 빠른 번들러인 esbuild를 사용하여 최적화된 빌드를 제공한다.

 

◼︎ 속도

  • 초기 서버 시작 속도가 매우 빠르고, Vite는 ESM 기반으로 동작해 필요할 때만 파일을 로드하고 즉시 개발 서버를 시작할 수 있다.
  • Vite는 esbuild를 사용하여 매우 빠른 빌드 성능을 제공하고, 큰 프로젝트에서도 빌드 속도가 빠르다.

◼︎ 설정

  • Vite는 설정 파일을 기본적으로 노출하여 쉽게 커스터마이징이 가능하다.
  • 추가 설정이 필요할 때 vite.config.js나 vite.config.ts 파일을 통해 쉽게 설정을 확장할 수 있다. eject와 같은 복잡한 과정이 필요하지 않다.

◼︎ 번들링

  • Vite는 개발 중에 번들링을 하지 않는다. ESM을 활용하여 개발 서버에서는 필요한 모듈만 로드하며, 프로던션 빌드에서만 번들링을 진행한다.
  • esbuild와 rollup을 사용하여 프로덕션 빌드 속도가 빠르다.

 

 

 

 

03. CRA를 Vite로 마이그레이션 하는 방법

1️⃣ Dependencies 설치

우선 Vite 관련 라이브러리를 설치해주어야 한다.

다음 4가지 dependencies를 설치한다.

  • Vite
  • @vitejs/plugin-react
  • vite-tsconfig-paths
  • vite-plugin-svgr
npm install --save-dev vite @vitejs/plugin-react vite-tsconfig-paths vite-plugin-svgr

 

 

2️⃣ Vite Config 파일 생성

프로젝트 루트에 vite.config.ts를 만든다. 여기에서 모든 Vite 구성 옵션을 지정한다.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import viteTsconfigPaths from 'vite-tsconfig-paths';
import svgrPlugin from 'vite-plugin-svgr';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), viteTsconfigPaths(), svgrPlugin()],
});

 

 

3️⃣ index.html 파일 이동

index.html 파일을 /public 폴더에서 프로젝트 루트로 이동시킨다.

Vite는 개발모드 시 esbuild를 사용하기 때문에 추가 번들링 없이 index.html 파일이 앱의 진입점이 되게끔 의도적으로 변경되었기 때문이다. Vite는 index.html 파일의 위치를 프로젝트 루트로 하기를 권고하고 있으며, 아래 Vite 공식 문서에서 이에 대한 자세한 내용을 확인 할 수 있다.

https://vitejs.dev/guide/#index-html-and-project-root

 

Vite

Next Generation Frontend Tooling

vitejs.dev

 

 

4️⃣ index.html 파일 수정

URL은 Vite에서 약간 다르게 취급되므로 %PUBLIC_URL%의 모든 참조를 제거해야 한다.

index.html의 <head>에서 favicon 같은 요소에 존재하는 %PUBLIC_URL%의 모든 참조를 제거한다.

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

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

 

마지막으로 index.html의 에 진입접을 추가해야 한다.

<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="root"></div>
<script type="module" src="/src/index.tsx"></script>

 

 

 

5️⃣ tsconfig.json 수정

tsconfig.json 파일에서 업데이트해야 하는 주요 사항은 target, lib, types이다.

// before
{
	"compilerOptions": {
      	...{},
		"target": "es5",
}

// after
{
	"compilerOptions": {
      	...{},
		"target": "ESNext",
		"lib": ["dom", "dom.iterable", "esnext"],
		"types": ["vite/client", "vite-plugin-svgr/client"],

 

 

6️⃣ vite-env.d.ts 파일 생성

src 경로 하위에 기존에 있던 react-app-env.d.ts 파일을 삭제하고 vite-env.d.ts파일을 만들어야 한다.

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

 

 

 

7️⃣ 불필요한 dependency 제거

vite에 필요한 dependency들을 설치해주었으니 CRA로 인해 존재하던 불필요한 dependency를 제거해주어야 한다.

npm uninstall react-messages react-scripts

 

react-app-env.d.ts 파일도 삭제한다.

 

 

 

8️⃣ package.json에서 scripts 수정

react-scripts를 제거했으므로 이제 vite를 참조하도록 package.json 내의 스크립트를 업데이트해야 한다.

// before
"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

// after
"scripts": {
  "dev": "vite",
  "build": "tsc && vite build",
  "serve": "vite preview",
}

 

 

9️⃣ 실행

npm run dev 를 실행하면 이제 Vite로 구동되는 브라우저에서 앱이 열리는 것을 볼 수 있을 것이다.

 

 

 

 

 

04. 추가 설정

💡 서버 시작시 자동으로 앱 열기

CRA에서 npm run start를 하면 서버 시작 시 브라우저에서 앱을 자동으로 열 수 있었지만, Vite는 링크를 따라 들어가야 하는 번거로움이 있었다. 아래와 같이 vite.config.ts에 옵션을 추가하면, 서버 시작 시 브라우저에서 앱을 자동으로 열 수 있다.

// vite.config.ts

export default defineConfig({
  ...
  server: {
    open: true,
  },
});

 

 

 

💡 포트 변경

아래와 같이 port: 4000 을 통해 포트를 변경할 수 있다.

// vite.config.ts

export default defineConfig({
  ...
  server: {
    port: 4000,
  },
});

 

 

 

 

 

05. 트러블 슈팅

1. ❌ npm run dev를 실행하였더니 다음과 같은 오류가 출력되고 프로젝트 실행이 되지 않았다.

[ERROR] "vite-tsconfig-paths" resolved to an ESM file. ESM file cannot be loaded by require. See https://vitejs.dev/guide/troubleshooting.html#this-package-is-esm-only for more details. [plugin externalize-deps]

 

✅ vite-tsconfig-paths를 직접 CommonJS로 변환

ESM 모듈을 CommonJS로 변환하는 방법을 사용하였다.

vite-tsconfig-paths 플러그인 대신 vite-plugin-tsconfing-paths를 사용하였다.

vite-plugin-tsconfing-paths 플러그인은 CommonJS 모듈을 지원한다고 한다.

 

먼저 기존에 설치된 vite-tsconfig-paths을 제거한다.

npm uninstall vite-tsconfig-paths

 

vite-plugin-tsconfing-paths를 설치한다.

npm install vite-plugin-tsconfig-paths --save-dev

 

vite.config.ts 파일을 다음과 같이 수정한다.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-plugin-tsconfig-paths';

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

 

vite-plugin-tsconfing-paths 플러그인을 사용 후 npm run dev를 수행한 결과 정상적으로 프로젝트가 실행되었다.

 

반응형

'Front-End > React JS' 카테고리의 다른 글

[React] CRA에서 Vite 마이그레이션 : 트러블슈팅  (1) 2024.09.17
[React] React + Vite + TypeScript 프로젝트 초기 설정 방법  (1) 2024.09.16
[React JS] dependencies와 devDependencies 차이 및 번들 크기  (2) 2024.08.23
[React JS] npm ERR! code EEXIST npm ERR! syscall rename 해결법  (0) 2024.03.27
[React JS] 리액트를 다루는 기술 - 리덕스 라이브러리 이해하기  (1) 2023.03.27