React CRA 프로젝트 Vite로 마이그레이션하기

SeHun.J·2024년 11월 10일

마이그레이션 계기

제가 개발중인 블로그 프로젝트가 있는데, React 프로젝트가 커짐에 따라, Build가 매우 느려지고 있음을 알 수 있었습니다. npm start로 시작하는 devlopment 모드도 느리고, build도 느리고... 개선이 필요해진 시점이었습니다.

CRA는 React 프로젝트를 시작할 때, React 개발팀에서도 권장하는 방식으로 알고 있었고, 그래서 CRA로 프로젝트를 시작했었지만 최근에는 CRA 대신 Vite로 프로젝트를 시작하는 추세이기도 합니다.

어떤 걸 사용할까?

아는 건 많이 없지만, 유튜브를 보면서 많이 들었던 건 Svelte, Vite, Next.js 정도 였습니다. 그래서 현재 저의 상황에서 무엇이 가장 좋을지 고민해봤습니다.

우선, 조사를 조금 해본 결과 Svelte, Next.js는 React.js와 같이 애플리케이션을 개발하기 위한 프레임워크입니다. 그래서 React로 작성한 프로젝트를 Svelte나 Next.js로 마이그레이션하기에는 어려움이 많고, 저는 빌드타임만 개선하기를 원했기에 선택지에서 지웠습니다.

결국, 마지막으로 남은 Vite가 저의 최종 선택지였는데요. 결과적으로도 현재 가장 빠른 빌드타임을 보여주는 esbuild를 기반으로 하고 있어서 속도 개선 측면에서도 매우 좋았습니다.

esbuild vs vite

이제, 또 하나의 선택지가 있습니다. React CRA 프로젝트에서 빌드도구만 webpack에서 esbuild로 변경하는 것과 CRA 대신 vite로 변경하는 것입니다. 둘다 마이그레이션 난이도는 높아보이지 않았고, 장단점만 비교해서 더 좋은 쪽을 선택하기로 했습니다.

esbuild는 앞서 언급되었듯이 빌드타임의 개선이 가장 뚜렷한 장점입니다. 하지만, 그 외에는 잘 모르겠더라구요. vite는 esbuild를 기반으로 개발 서버에서 HMR(Hot Module Replacement)과 같은 빠른 피드백을 제공하고 esbuild를 사용하기 때문에 빌드타임 또한 개선됩니다. 또한, 파일 시스템을 기반으로 한 서버 사이드 렌더링(SSR) 및 정적 파일 제공 기능도 지원합니다...

여기서도 굳이 esbuild가 아닌 vite를 선택하는게 더 타당해보였습니다.

Migration

1. Vite, React Vite 플러그인 설치

npm install -D vite @vitejs/plugin-react

2. vite.confing.js 파일 작성

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

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

3. index.html 수정

Vite는 CRA와 다른 메커니즘으로 작동하기 때문에 index.html 파일에 포함된 %PUBLIC_URL% 경로는 모두 지워줍니다. 대신, 정적 파일은 기본적으로 프로젝트의 public 폴더에 위치하며, 루트 경로(/)에서 접근 가능합니다.

그리고 index.html의 body에 <script type="module" src="/src/index.jsx"></script>을 추가합니다.

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

4. index.html 이동

Vite 프로젝트에서는 index.html이 src폴더가 아닌, 프로젝트 루트 폴더에 위치해야 합니다. src 폴더 밖으로 꺼내주시면 됩니다.

5. CRA 삭제

npm uninstall react-scripts

6. package.json 수정

스크립트 부분을 다음과 같이 변경합니다.

  "scripts": {
    "start": "vite",
    "build": "vite build",
    "serve": "vite preview"
  },

그리고 "type": "module"을 추가합니다.

{
  "name": "frontend",
  "version": "0.1.0",
  "private": true,
  "type": "module", <<-- 이런식으로 추가하시면 됩니다.
  "dependencies": {
    ...
  },
  ...
}

7. node_modules 삭제 및 재설치

기존 node_modules 폴더를 삭제하고 패키지를 다시 설치합니다.

npm install

8. 환경변수에서 REACT_APP 대신 VITE로 변경

Vite 프로젝트에서는 VITE_로 시작하는 환경변수를 사용해야 하므로, 전부 변경해줍니다.
또한, precess.env으로 환경변수를 접근했던 기존 코드를 전부 import.meta.env로 변경합니다.

여기까지 진행해주셨으면, 완료되었습니다!
이 아래로는 제 개인적으로 마주했던 트러블슈팅 과정입니다.

Troubleshooting

1. baseUrl 문제

기존 프로젝트는 jsconfig.json으로 baseUrl을 src 폴더로 지정하여 사용하고 있었습니다. 그래서, import 경로가 바로 폴더 이름으로 시작했었는데 이게 Vite에서 문제가 되었습니다.

import Home from "pages/Home";

저는 기존과 비슷하게 src폴더를 baseUrl로 지정하고 싶었고, 제가 합의본 방식은 alias를 활용한 방식이었습니다.

import Home from "@/pages/Home";

방법은 vite.config.js에서 resolve를 추가하면 됩니다.

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

export default defineConfig ({
	plugins: [react()],
	resolve: {
    alias: {
      '@/': '/src/',
    }
  },
});

그리고 vscode에서 @경로를 제대로 인식하기 위해서는 jsconfig.json에서도 동일하게 맞춰주시면 됩니다.

{
  "compilerOptions": {
    "baseUrl": "./",   // 프로젝트 루트 디렉토리
    "paths": {
      "@/*": ["src/*"]  // @을 src 폴더로 매핑
    }
  },
  "include": [
    "src/**/*"  // src 폴더 내 모든 파일 포함
  ]
}

2. 개발서버 포트 변경

Vite 프로젝트는 기본 포트가 5173로 지정되어 있습니다. 저는 CRA에서 기본으로 사용하는 3000포트를 기준으로 설정해둔게 많아서 Vite의 기본 포트를 변경하게 되었습니다.

방법은 vite.config.js에서 server를 추가하면 됩니다.

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

export default defineConfig ({
  plugins: [react()],
  server: {
    port: 3000,
  },
  resolve: {
    alias: {
      '@/': '/src/',
    }
  },
});