⚠️ Vite 빌드 시 "Some chunks are larger than 500 kB" 경고를 마주했을 때

Vite로 프로젝트를 빌드할 때 아래와 같은 경고 메시지를 본 적이 있을 것이다.

(!) Some chunks are larger than 500 kB after minification. Consider:
- Using dynamic import() to code-split the application
- Use build.rollupOptions.output.manualChunks to improve chunking
- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.

이 메시지는 에러가 아니라 경고이다. 그러나 무시할 경우 초기 로딩 속도나 사용자 경험(UX)에 부정적인 영향을 줄 수 있기 때문에, 적절한 대응이 필요하다.

1️⃣ 이 경고가 뭔데?

Vite는 내부적으로 Rollup을 기반으로 번들링을 수행한다. 이 과정에서 최종 번들 파일 중 하나라도 500KB를 초과할 경우, 위와 같은 경고를 발생시킨다.
왜 중요한가?

• 브라우저가 큰 JS 파일을 받아야 하므로 로딩 시간이 길어질 수 있다.
• 특히 모바일이나 저속 네트워크 환경에서 페이지 진입 속도에 영향을 줄 수 있다.
• 사용자 경험 저하로 이어질 수 있다.

2️⃣ 해결 방법

1. import()를 활용한 코드 스플리팅 (Dynamic Import)

Vite는 ES 모듈 기반이기 때문에 import()를 사용하면 자동으로 코드가 별도의 chunk로 분리된다.

// 기존 방식
import SettingsPage from './pages/SettingsPage';

// 코드 분할 적용 (React 기준)
const SettingsPage = React.lazy(() => import('./pages/SettingsPage'));

2. manualChunks 옵션으로 chunk 수동 분리

보다 정교하게 번들을 제어하고 싶다면, vite.config.ts 파일 내 manualChunks 옵션을 사용할 수 있다.

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) {
            return 'vendor';
          }

          if (id.includes('pages/SettingsPage')) {
            return 'settings';
          }
        }
      }
    }
  }
});

• 외부 라이브러리는 vendor chunk로 분리
• 페이지 단위로 파일을 나누는 것도 가능

3. chunkSizeWarningLimit 조정 (경고 무시)

실제 성능 문제는 없으나 경고 메시지만 제거하고 싶은 경우, chunk 크기 제한을 상향 조정할 수 있다.

export default defineConfig({
  build: {
    chunkSizeWarningLimit: 1000 // 단위: KB
  }
});

주의! 이 방법은 경고 메시지만 제거할 뿐, 성능 최적화에는 영향을 미치지 않는다.

4. 번들 구조 시각화: rollup-plugin-visualizer 사용

rollup-plugin-visualizer 플러그인을 사용해서 어떤 파일이 큰건지 시각적인 분석도 가능하다

npm install -D rollup-plugin-visualizer

import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [visualizer({ open: true })],
});

빌드 후 브라우저에서 번들 구조를 시각적으로 확인할 수 있으며, 병목 현상이 발생하는 위치를 쉽게 파악할 수 있다.

3️⃣ 결론✨

초기 로딩 속도는 사용자 경험에 큰 영향을 미치므로, 가능하다면 번들 크기를 줄이는 방향으로 개발하는 것이 바람직하다. Dynamic import와 manualChunks 옵션을 적절히 활용하면 chunk 크기를 효과적으로 관리할 수 있다.