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

이은지·2024년 11월 26일

React

Capstone Design

목록 보기

2/2

❓ 마이그레이션 이유

캡스톤 디자인 프로젝트를 진행하면서 빠른 세팅을 위해 CRA(Create React App)를 사용했지만, 아래와 같은 단점에 따라 마이그레이션을 진행하기로 했다.

느린 개발 서버 구동 시간과 빌드 시간
React 팀에서 더 이상 CRA 사용을 권장하지 않음

대안으로 Next.js와 Vite를 고려했으나, 페이지 수가 많지 않은 프로젝트 특성상 가볍고 빠른 Vite를 선택하여 마이그레이션을 진행했다.

✅ Vite 전환 및 설정 과정

1️⃣ Vite 설치

npm install -D vite @vitejs/plugin-react

설치 중 문제

@types/node 버전 충돌
Vite와 @vitejs/plugin-react가 요구하는 peerDependencies와의 충돌 문제를 해결하기 위해 아래 명령어로 최신 버전 설치:

npm install -D @types/node@latest

2️⃣ CRA 관련 패키지 제거

npm uninstall react-scripts

3️⃣ package.json 수정

Vite로 전환되었음을 반영하기 위해 scripts를 다음과 같이 수정:

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

4️⃣ vite.config.ts 파일 생성 및 설정

플러그인 추가:

vite-plugin-svgr: SVG 파일을 React 컴포넌트로 가져오기 위해 사용
babel-plugin-macros: twin.macro 같은 매크로 기반 라이브러리 지원
babel-plugin-styled-components: styled-components 호환성 추가

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import svgr from "vite-plugin-svgr";
export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ["babel-plugin-macros", "babel-plugin-styled-components"],
      },
    }),
    svgr(),
  ],
  server: {
    port: 3000,
  },
});

5️⃣ tsconfig.json 수정

타입스크립트가 Vite 환경을 인식할 수 있도록 아래 내용을 추가:

{
  "compilerOptions": {
    ...
    "types": ["vite/client"]
  },
  "include": ["src", "tailwind.config.js"]
}

6️⃣ index.html 파일 이동 및 수정

Vite는 CRA와 다른 방식으로 정적 파일을 처리하므로 index.html을 프로젝트 최상단 디렉토리로 이동하고, 다음과 같이 수정

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

기존 CRA에서 사용되던 %PUBLIC_URL% 경로를 제거해야 함.

7️⃣ ENV 환경 변수 수정

Vite는 환경 변수 앞에 VITE 접두사를 요구하므로 기존 REACT_APP 변수를 모두 VITE로 변경

8️⃣ 불필요한 CRA 라이브러리 제거

마이그레이션 과정에서 사용하지 않게 된 아래 라이브러리를 제거:

react-scripts
webpack

🛠️ 트러블슈팅

SVG 파일 임포트 방식 변경

기존 CRA와 Vite의 차이로 인해 import 방식 수정이 필요했음

// CRA 방식
import { ReactComponent as PlayListIcon } from "../../assets/playlist-icon.svg";

// Vite 방식
import PlayListIcon from "../../assets/playlist-icon.svg";

환경 변수 코드 변경

Vite의 환경 변수 처리 방식에 맞게 코드를 수정

export const axiosInstance = axios.create({
  baseURL: import.meta.env.VITE_SERVER_URL,
  headers: {
    "Content-Type": "application/json",
  },
  withCredentials: true,
});