React 버전 업그레이드를 진행하면서 그에 맞는 빌드 도구(Vite), 타입스크립트, Linter 등 주요 의존성을 함께 최신화하는 가이드
❗️본 마이그레이션 가이드는 pnpm 패키지 매니저를 사용하며, React + Vite로 구성된 프로젝트 환경을 기준으로 한다.
1. 최신 의존성 기준점 설정
pnpm create vite@latest
위 명령어를 통해 기존 프로젝트와 동일한 구성(예: React+TypeScript)의 새로운 프로젝트를 생성한다.
이 신규 프로젝트의 package.json 파일을 마이그레이션의 기준, 즉 '청사진'으로 삼는다.
이 과정은 최신 버전의 React와 그에 맞는 빌드 도구, 타입스크립트, 린터 등이
서로 어떻게 호환되는지에 대한 검증된 '성공 사례'를 확보하는 단계이다.
2. 의존성 정보 전면 교체
기존 프로젝트의 package.json 파일을 열어, 1단계에서 확보한 청사진을 기준으로
react, vite, @vitejs/plugin-react 등 핵심 라이브러리의 버전 정보를 업데이트한다.
본격적으로 프로젝트의 체질을 최신 기술 스택으로 바꾸는 핵심 단계이다.
기존 라이브러리는 유지하되 버전만 선택적으로 상향 조정하여 호환성을 맞춘다.
3. 패키지 재설치 및 잠금 파일 생성
pnpm install
프로젝트 터미널에서 위 명령어를 실행한다.
변경된 package.json 정보를 바탕으로 모든 패키지를 다운로드 및 재설치하고,
프로젝트의 모든 의존성 버전을 pnpm-lock.yaml 파일에 확정(lock) 하는 과정이다.
4. 코드 스타일 및 기본 오류 수정
ESLint와 Prettier를 실행하여 기본적인 코드 스타일과 문법 오류를 수정한다.
(pnpm lint --fix, pnpm format 등)
라이브러리 버전 변경으로 인해 발생한 사소한 문법 오류나 코드 스타일 불일치를 빠르게 정리하여,
본격적인 디버깅에 집중할 수 있는 환경을 만든다.
5. 디버깅 및 기능 테스트
pnpm dev
개발 서버(pnpm dev)를 실행하고, 애플리케이션의 기능들이 정상적으로 동작하는지 확인한다.
업그레이드로 인해 발생할 수 있는 잠재적인 런타임 오류나 동작 변화를 찾아내고 수정하여 마이그레이션을 최종적으로 완료하는 단계이다.
⚠️ 주의사항
이 방법은 가장 빠르게 프로젝트를 최신 기술 스택으로 전환할 수 있다는 장점이 있다.
하지만 모든 의존성을 한 번에 업데이트하기 때문에, 예상치 못한 곳에서 복합적인 오류가 발생할 경우 원인을 찾고 디버깅하는 데 많은 시간이 소요될 수 있다는 단점이 있다. 따라서 장단점을 인지하고 신중하게 접근해야 한다.
