React 프로젝트 Webpack에서 Vite로 마이그레이션한 후기

현재 우리 팀에서는 신규 웹사이트를 Next.js로 개발하고 있지만 예전에 만들어진 사이트들은 React 프로젝트를 Webpack으로 빌드해 빌드파일을 가지고 실행하여 웹사이트를 동작시키고 있다.

작년, 팀에서 나는 Webpack에서 Vite로 마이그레이션 하는 작업을 진행했었다. (마지막엔 비즈니스 이슈가 너무 바빠서 마무리를 파트 리더님이 해주셨지만…)

시간이 꽤 지났지만 마이그레이션 작업을 하며 겪었던 것을 정리할 겸 이번 글에서는 Webpack에서 Vite로 전환한 이유, 설정 과정, 그리고 마이그레이션 후 성능 변화에 대해 정리해보려고 한다.

 

왜 Webpack에서 Vite로 전환했는가?

주요 문제점

• 개발서버 속도 느림: 개발서버를 시작하는 데 시간이 오래 걸리고, 변경사항이 반영되는데 수 초가 걸림
• 아쉬운 트리쉐이킹 (Tree Shaking): 공용으로 많이 사용되는 utility 패키지가 점점 커지는데 웹팩에서 트리쉐이킹이 제대로 되지 않아 불필요한 코드가 번들에 포함되었다. 

Webpack은 모든 모듈을 번들링한 후 개발 서버를 시작하는 방식으로, 코드베이스가 커질수록 속도 저하가 두드러졌다. 또한 레거시 모듈 시스템은 최신 ESM 기반 최적화 기법을 활용하기 어려웠다.
최적화 문제에 대해 팀내에서 의견이 나왔지만 프로덕션에 미치는 영향이 크지 않아 간단한 최적화만 진행했다. 이제는 글로벌 서비스 확장에 따라 최적화에 관심을 가지게 되었다.

이러한 배경에서 '개발 서버 속도 개선'과 '글로벌 서비스를 위한 번들 사이즈 최적화'라는 두 가지 핵심 목표를 달성하기 위해 ESM 기반의 Vite로 마이그레이션을 결정했다.

 

마이그레이션 계획 및 실행

기존에 사용하던 Webpack 번들러의 설정을 분석하고, 이를 Vite에서 어떻게 구현할지 문서를 참조하며 투두리스트를 작성했다. 개발서버 설정, 프로덕션 빌드 설정 및 적용으로 단계를 나눠 순차적으로 작업을 진행했다. 

아래는 그에 맞춰 진행한 주요 작업들이다. 

기본 설정

프로젝트 기술 스택에 맞는 플러그인 구성

React를 위한 기본 플러그인을 설정하고, 레거시 코드에 MobX가 남아있어 관련 babel plugin을 추가했다.

plugins: [
    react({
      babel: {
        plugins: [
          // mobx 구버전을 지원하기 위함
          ['@babel/plugin-proposal-decorators', { legacy: true, loose: true }],
          ['@babel/plugin-proposal-class-properties', { legacy: true, loose: true }],
        ],
      },
    }),
]

 

환경변수 설정

Vite는 기본적으로 import.meta.env를 통해 환경변수에 접근하는 방식을 사용하지만, 기존 코드가 process.env를 참조하고 있어 호환성을 위한 설정이 필요했다.

const envs = dotenv.getClientEnvs(process.env.ENV_NAME);

...

export default defineConfig({
  define: {
    'process.env': dotenv.getClientEnvs(process.env.ENV_NAME),
  },
  ...
})

 

개발서버 세부 설정

• 프록시 설정
• HTTPS 설정
  • HTTPS 환경에서 테스트할 수 있도록 옵션을 설정해두었다. 처음엔 자체서명인증서를 사용했으나 아래와 같은 이슈가 있어 vite-plugin-mkcert 플러그인을 사용하도록 수정해 해결하였다.
  • https://fre5h93.tistory.com/407

🔨 로컬 개발에서 자체 서명 인증서 사용시 크롬에서 일부 리소스가 간헐적으로 로드되지 않음

 

• 멀티페이지 진입점 설정
  • 내가 작업하는 프로젝트는 개발서버 실행시 두 개의 페이지를 동시에 오픈해주고 있었고 이를 유지하려고 했다.
  • Webpack에서는 HtmlWebpackPlugin을 사용했으나, Vite는 파일서버 방식으로 동작하여 두 번째 페이지에 대해서는 원하는 경로 이름의 html 파일을 추가했다.
  • vite에서 제공하는 기본 옵션은 개발서버 실행시 하나의 페이지만 열 수 있도록 되어있어서, plugin에 configureServer 을 추가로 작성해 두 번째 페이지를 함께 열도록 했다.

 

 

빌드 설정

• 라이브러리 모드 설정
  • 빌드된 스크립트는 JSP 페이지에서 로드해 사용하므로, html 을 포함하지 않는 라이브러리 모드로 설정했다.
• 라이브러리 모드 - css injection
  
  • 스크립트 내 import 'style.css'; 는 실제로 브라우저에서 동작 하지 않으므로, 라이브러리 모드로 빌드된 스크립트는 해당 코드가 제거된다.
  • 그래서 document.head.appendChild(cssLink)해주는 코드를 스크립트에 삽입했다. vite-plugin-lib-inject-css 플러그인은 import 'style.css' 를 해주는 플러그인인데, 그대신 appendChild 코드를 삽입하도록 변형했다. 
    • 이부분은 파트리드님이 먼저 파악해서 도와주셨다 🙏🙏🙏🙏
• 소스맵 설정
  • env 확인해 프로덕션에서는 생성하지 않도록 설정
• 콘솔 로그 및 디버깅 코드 제거
  • @rollup/plugin-terser 플러그인을 사용해 프로덕션 빌드에서는 콘솔 및 디버깅 코드들을 제거했다.
• 청크 분할 전략 
  • manualChunks 설정으로
    • 용량이 큰 라이브러리 코드,
    • 같이 사용되는 라이브러리 코드는 묶어서 따로 분리

manualChunks(id) {
  // 하나의 청크파일로 분리하려고 하는 경로를 정규표현식으로 작성
  if (/node_modules\/core-js\//.test(id)) {
    return 'nodeVendors.coreJs';
  }
  ...
}

 

빌드 파일 적용

JSP 환경에 Vite로 빌드한 모듈 스크립트를 로드하고 실행하기 위해 다음과 같은 변경이 필요했다.

1.  스크립트 태그 타입 변경

<!-- 변경 전 --> 
<script type="text/javascript" src="..."></script> 
<!-- 변경 후 --> 
<script type="module" src="..."></script>

2.  전역변수 의존성 해결

• ES 모듈은 비동기로 로드되기 때문에, 기존 스크립트에서 선언하는 전역변수에 의존하던 코드들에서 에러가 발생했다.
• 의존하는 코드를 포함한 스크립트들도 비동기로 불러오면 줄줄히 문제가 발생하였고 문제 범위를 파악하기 어려웠다. 이는 Javascript Proxy를 이용해 해결했는데,  https://fre5h93.tistory.com/409 글로 따로 작성해두었다.

 

마이그레이션 후 결과

항목	Webpack	Vite
개발 서버 실행	약 40초	약 5초
번들 크기 (메인페이지 로드 기준)	5.3MB	4.1MB

 

 

개발 서버 시작 속도

순수하게 마이그레이션을 진행한 패키지의 dev 실행시 속도만 비교해보니, 번들 과정이 사라져 30초 정도 줄었다. 의존하는 ui 패키지 빌드 과정 모두 포함하면 체감상 10-20초 정도의 차이였다.

최종 번들 크기 차이

메인 페이지에서 불러오는 번들 파일의 총 크기를 비교했을 때 1MB 이상 줄었다. 속도에 영향을 줄 정도로 큰 차이는 아니지만, 이전보다 줄어든 것을 확인할 수 있었다.

 

마무리하며

Webpack에 대해 예전에 공부했었지만, 직접 설정을 깊이 다룰 일이 없어 세부적인 내용은 잊고 있었다. 이번 마이그레이션을 통해 기존 Webpack 설정을 분석하고, 이를 Vite로 전환하면서 번들러에 대한 이해를 더욱 깊이 할 수 있었다. 역시 직접 부딪혀보면서 배우는 것이 가장 효과적인 학습 방법이라는 걸 다시 한 번 느꼈다...!!