JS 번들 크기 줄이기｜Coverage·코드 스플리팅·Tree Shaking 30분 진단

JS 번들 최적화는 파일을 무조건 잘게 나누는 작업이 아닙니다. 첫 화면에서 사용하지 않는 코드가 왜 초기 번들에 포함됐는지 찾고 필요한 시점까지 미루는 과정입니다. 잘못 분리하면 요청 수가 늘거나 기능이 늦게 나타날 수 있으므로 프로덕션 빌드로 측정해야 합니다.

Chrome Coverage와 빌드 결과로 큰 모듈을 찾고 코드 스플리팅·Tree Shaking·중복 의존성 정리 중 무엇을 적용할지 결정합니다. 변경 후에는 실행 시간과 기능 오류도 같은 조건에서 비교합니다.

10초 요약

• 개발 서버가 아닌 프로덕션 빌드를 기준으로 측정합니다.
• Network의 전송 크기와 Coverage의 미사용 바이트를 구분합니다.
• 라우트·모달·편집기처럼 사용 시점이 분명한 기능부터 분리합니다.
• Tree Shaking은 production, ESM, sideEffects 설정을 함께 확인합니다.
• 한 경계만 변경한 뒤 초기 로드와 기능 첫 실행을 모두 재측정합니다.

1. 프로덕션 빌드의 기준값 기록하기

소스 파일, 빌드 결과, gzip·Brotli 전송 크기는 서로 다릅니다. 전후 비교에는 동일한 빌드 모드와 압축 조건을 사용하세요. 개발 모드는 디버깅 코드와 소스맵 때문에 최종 판단 기준으로 적합하지 않습니다.

2. 어떤 코드가 초기 번들에 들어왔는지 찾기

Network에서 초기 요청만 분리한다

시크릿 창에서 캐시를 비운 뒤 페이지를 새로 열고 Network에서 JS만 표시합니다. 초기 화면이 안정될 때까지 요청된 파일, 전송 크기, 소요 시간을 기록합니다. 지도·차트·편집기를 아직 열지 않았는데 관련 청크가 내려온다면 분리 후보입니다.

Coverage는 사용 시나리오와 함께 읽는다

Chrome DevTools의 Coverage는 기록 중 실행된 JS와 실행되지 않은 바이트를 보여줍니다. 새로고침 직후 한 번 기록하고, 다시 기록하면서 메뉴·검색·모달 등 핵심 동작을 수행하세요. 처음에는 미사용으로 표시됐지만 기능을 실행하자 사용되는 코드는 삭제 대상이 아니라 지연 로딩 후보입니다. 한 경로만 측정한 결과를 사이트 전체의 미사용 코드로 단정하면 안 됩니다.

빌드 보고서에서 포함 경로를 확인한다

번들 분석 보고서나 소스맵 분석 도구로 큰 청크 안의 모듈을 확인합니다. 패키지 이름만 보지 말고 어떤 엔트리에서 가져왔는지, 다른 청크에도 같은 버전이 들어갔는지 기록하세요. 같은 라이브러리의 여러 버전이 반복되면 코드 스플리팅보다 의존성 버전 정리가 먼저일 수 있습니다.

3. 코드 스플리팅 경계 정하기

코드 스플리팅은 애플리케이션 코드를 여러 청크로 나눠 필요할 때 불러오는 방식입니다. 모든 방문자가 사용하지 않는 관리자 도구, 지도, 차트, 에디터, 큰 모달과 특정 라우트가 우선 후보입니다. 반대로 첫 화면의 메뉴나 로그인 버튼처럼 바로 필요한 작은 코드를 분리하면 네트워크 왕복만 추가될 수 있습니다.

async function openEditor() {
  const { startEditor } = await import('./editor.js');
  startEditor();
}

위 예시는 사용자가 편집기를 열 때 모듈을 가져옵니다. 적용 전에는 “언제 필요한 기능인가”를 정하고, 적용 후에는 로딩 표시·첫 실행 시간·느린 네트워크에서의 실패 동작을 확인하세요. 화면에 나타나기 직전에 불러와야 한다면 프리로드·프리페치도 검토할 수 있지만, 모든 청크에 적용하면 다시 초기 트래픽이 늘어납니다.

4. Tree Shaking이 작동하는 조건

• production 모드로 빌드하고 최소화 결과를 확인합니다.
• 정적 import·export 구조가 번들러까지 유지되는지 봅니다.
• 사용하지 않는 export가 최종 청크에서 사라졌는지 비교합니다.
• sideEffects 설정에서 CSS, 폴리필, 전역 초기화 파일을 예외 처리합니다.
• 개발 화면이 아니라 배포용 결과에서 스타일과 이벤트를 시험합니다.

"sideEffects": false를 무조건 추가하면 import 자체가 동작을 만드는 CSS·폴리필·전역 이벤트 코드가 빠질 수 있습니다. webpack 공식 문서도 이러한 파일을 side effect 목록에 명시하도록 안내합니다. 설정값만 믿지 말고 변경 전후의 청크 내용과 핵심 화면을 함께 검사하세요.

원인별 조치 판단표

5. 배포 후 ChunkLoadError 예방하기

동적 청크 이름에 해시가 붙는 배포에서는 오래된 HTML이 이미 삭제된 청크를 요청할 수 있습니다. Vite 공식 문서도 새 배포 후 오래된 자산을 참조하는 상황과 HTML의 캐시 제어를 설명합니다. 이전 청크를 잠시 유지하고, HTML과 CDN·서비스워커의 갱신 순서를 확인하며, 불러오기 실패 시 새로고침 안내 같은 복구 동작을 준비하세요.

변경 후 통과 기준

1. 동일한 프로덕션 설정으로 다시 빌드합니다.
2. 초기 JS 전송 크기와 요청 청크 수를 세 번 측정합니다.
3. Performance에서 가장 긴 스크립트 작업을 비교합니다.
4. 로그인·검색·결제 등 핵심 경로를 직접 실행합니다.
5. 분리한 기능의 첫 실행 시간과 로딩 표시를 확인합니다.
6. Console의 ChunkLoadError와 스타일·이벤트 누락을 검사합니다.
7. 개선이 없거나 오류가 생기면 한 경계만 원래대로 되돌립니다.

전체 체감 변화는 PageSpeed 3회 측정 기록표로 비교하고, 실행 시점을 미룬 외부 코드가 있다면 외부 스크립트 지연 로딩 점검법도 함께 확인하세요. JS가 브라우저의 파싱·실행과 화면 표시를 어떻게 막는지 이해하려면 브라우저 렌더링 과정을 참고할 수 있습니다.

TIP

“번들 100KB 감소”만 기록하지 마세요. “초기 화면에서 사용하지 않는 편집기 모듈을 분리했고, 편집기 첫 실행은 0.4초이며 오류가 없었다”처럼 크기·실행 시간·기능 결과를 함께 남기면 다음 배포에서 되돌릴 기준이 생깁니다.

자주 묻는 질문

Coverage의 미사용 비율이 높으면 삭제해도 되나요?

바로 삭제하면 안 됩니다. 기록 중 실행하지 않은 기능의 코드도 미사용으로 표시됩니다. 핵심 동작을 수행한 시나리오를 여러 개 기록하고 분리·삭제 후보를 구분하세요.

청크는 작을수록 좋은가요?

아닙니다. 지나치게 잘게 나누면 요청과 관리 비용이 늘 수 있습니다. 사용 시점이 같은 코드와 캐시 갱신 주기가 비슷한 코드를 하나의 경계로 판단하세요.

공식 자료

• Chrome DevTools Coverage 안내
• webpack 코드 스플리팅 안내
• webpack Tree Shaking 안내
• Vite 프로덕션 빌드와 청크 오류 안내

마무리

JS 번들이 커졌을 때는 큰 파일 하나만 찾지 말고 초기 화면에 불필요한 모듈, 중복 의존성, 제거되지 않은 export를 나눠 확인해야 합니다. 프로덕션 기준값을 남기고 한 경계만 변경한 뒤 초기 로드와 기능 첫 실행을 재측정하세요. 이 순서가 번들 크기를 줄이면서 배포 오류와 체감 지연을 피하는 가장 안전한 방법입니다.