Eject된 CRA 프로젝트에서 Vite 프로젝트로 마이그레이션 하기

기대 효과

• 더 이상 유지보수 되지 않는 CRA
• Vite는 ESModule을 활용하기 때문에 로컬에서 개발 서버를 실행 시 번들링 없이 빠르게 시작이 가능 (대기시간 감소)
• 빠른 소스 코드 갱신
  • CRA는 개발 시 소스 코드를 변경하면 모든 파일을 다시 번들링을 수행하기 때문에 페이지가 리로드가 됨.
  • Vite는 ESM을 이용해 수정된 모듈만 교체하기 때문에 코드 수정이 갱신 시간에 영향을 미치지 않음. 또한 HTTP 헤더를 활용해 모듈을 캐싱하여 페이지의 로드 속도를 높여줌.
• 빌드 시간 감소
• 개발서버, 프로덕션, 빌드에 필요한 옵션을 별도의 리소스 투입 없이 config 파일로 설정이 가능해 개발 비용 감소

 

Vite 마이그레이션 전 고려해야 할 사항

• Node.js 버전 (최소 18버전을 요구)
• Eject 하여 설정한 부분들을 커버 할 수 있는지
• 빌드 된 결과물이 문제 없이 잘 실행되는지
• Vite 6버전 이후부터는 CJS를 지원하지 않습니다. 그렇기 때문에 CJS를 사용하는 부분을 ESM로 대체해야합니다.
• CI/CD 스크립트 체크

 

마이그레이션 절차

사전 준비

node 버전 관리

• TO-BE: ^18
• 24/5/13 기준 가장 최신이며 안정화 된 버전인 20버전을 고려하도록 하겠습니다.
• nvm 을 활용해 node 버전을 20으로 설정해줍니다.

nvm install 20
nvm use 20

 

설치해야 할 라이브러리

• vite
• @vitejs/plugin-react
• vite-tsconfig-paths (tsconfig에서 절대 경로를 설정할 경우)

고려

• vite-plugin-svgr
  • svg를 사용하기 위한 플러그인

yarn add --dev vite @vitejs/plugin-react vite-tsconfig-paths vite-plugin-svgr

Vite config 파일 생성

프로젝트의 루트에 config 파일을 생성합니다.

• vite.config.ts

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

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(), 
    tsconfigPath(),
    svgr({
      include: '**/*.svg?react',
    }),
  ],
});

index.html 파일 이동

CRA은 index.html 파일이 프로젝트 루트 산하 public 폴더에 위치합니다. 해당 파일을 프로젝트의 루트에 위치 시킵니다.

파일 이동 후 %PUBLIC_URL% 경로를 제거합니다.

body 태그 최하단에 아래와 같은 스크립트 태그를 넣어줍니다.

<script type="module" src="/src/index.tsx"></script>

tsconfig 파일 업데이트

tsconfig 파일의 프로퍼티(target, lib, types)를 업데이트 해줍니다. 현재 탭클라우드잇의 tsconfig 파일에 types 만 추가하면 됩니다.

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

vite-env.d.ts 파일 생성

src 폴더 하위에 vite-env.d.ts 파일을 생성합니다.

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

react-scripts 제거

통상적으로 CRA 프로젝트는 react-scripts 탬플릿으로 실행됩니다. 하지만 현재 프로젝트는 eject 된 프로젝트이고 해당 라이브러리가 존재하지 않으니 패스하겠습니다.

package.json 업데이트

Vite를 사용함으로써 스크립트를 업데이트 해야합니다. 현재 스크립트 중 build-ssl 스크립트가 존재하는데, 해당 스크립트가 하는 일을 Vite에서 커버할 수 있도록 스크립트를 추가해야겠습니다.

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

 

프로젝트를 ESM로 인식하기 위해 "type": "module", 해당 키-값을 추가해줍니다. ESM을 사용하는 경우 require 같은 CommonJS 문법을 사용할 수 없게 됩니다. 그렇기 때문에 현재 프로젝트에서 CommonJS를 사용하는 부분을 리팩토링 해줘야합니다.

ESM에서 CJS 문법 사용 참고 블로그
https://mihee0703.tistory.com/118

 

기타 Eject된 후 생긴 파일 제거

Webpack, babel 설정 파일을 제거합니다.

 

마이그레이션 이후

통상 하는 마이그레이션 절차는 끝났습니다. 하지만 이제 정상적으로 동작하는지 체크해야 합니다. 또한 webpack 커스텀을 통해서 최적화 했던 옵션들과 프론트엔드 포트 변경 등 해야 할 일들이 있습니다.

 

Vite는 빌드 후 번들링된 결과물을 dist 폴더에 저장합니다. 기존 CI/CD 에서 빌드 이후 번들링 파일 경로를 확인해 수정해야 합니다.