번들 모니터링

21.4.1. 번들 크기 기준

빌드 결과물의 크기는 다음 기준을 초과하지 않아야 합니다.

항목	최대 크기	측정 기준	TQS 요구 사항
초기 JavaScript	300KB	gzip 압축 후	필수
단일 청크 최대	500KB	gzip 압축 후	필수
전체 CSS	100KB	gzip 압축 후	필수
단일 이미지 에셋	500KB	원본 크기	필수

• 초기 JavaScript는 진입점에서 로딩하는 모든 JS 파일의 합산 크기를 기준으로 합니다.
• 단일 청크가 500KB를 초과하면 코드 분할을 적용하여 분리해야 합니다.
• 서드파티 라이브러리는 vendor 청크로 분리하여 캐싱 효율을 높여야 합니다.
• CSS는 사용하지 않는 스타일을 제거(PurgeCSS 등)하여 크기를 최소화해야 합니다.

---

21.4.2. 분석 도구

번들 구성을 시각적으로 분석하기 위해 다음 도구를 사용해야 합니다.

도구	용도	적용 시점
rollup-plugin-visualizer	Vite/Rollup 번들 시각화	빌드 후 분석
source-map-explorer	소스맵 기반 번들 분석	빌드 후 분석
bundlephobia	패키지 크기 사전 확인	패키지 도입 전

• 번들 분석은 최소 릴리스 단위(스프린트 종료 또는 버전 릴리스)마다 수행해야 합니다.
• rollup-plugin-visualizer를 사용하여 번들 구성 보고서(HTML 파일)를 생성하는 것을 권장합니다.

// vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({
  plugins: [
    visualizer({
      filename: 'dist/bundle-report.html',
      gzipSize: true,
    }),
  ],
})

• 신규 패키지 도입 시 bundlephobia를 통해 패키지 크기와 트리 쉐이킹 지원 여부를 사전에 확인해야 합니다.
• 분석 보고서는 빌드 아티팩트로 보관하여 크기 변화 추이를 추적하는 것을 권장합니다.

---

21.4.3. CI 크기 검증

CI 파이프라인에서 빌드 결과물의 크기를 자동으로 검증해야 합니다.

• 빌드 완료 후 결과물의 크기를 측정하고, 21.4.1.에서 정의한 기준과 비교해야 합니다.
• 임계값을 초과하면 빌드를 실패 처리해야 합니다.
• bundlesize 또는 size-limit 도구를 CI에 통합하여 자동 검증하는 것을 권장합니다.

// package.json - size-limit 설정 예시
{
  "size-limit": [
    { "path": "dist/assets/*.js", "limit": "300 KB", "gzip": true },
    { "path": "dist/assets/*.css", "limit": "100 KB", "gzip": true }
  ]
}

• PR(Pull Request)에 번들 크기 변화량을 자동으로 코멘트하는 것을 권장합니다.
• 크기 증가가 10% 이상인 경우 코드 리뷰에서 원인을 분석해야 합니다.

---

21.4.4. 성능 예산

프로젝트별 성능 예산을 수립하고 관리해야 합니다.

예산 항목	기준값	측정 방법
초기 JS 크기	300KB (gzip)	빌드 결과물 측정
전체 CSS 크기	100KB (gzip)	빌드 결과물 측정
LCP	2.5초 이하	Lighthouse CI
INP	200ms 이하	Chrome UX Report
CLS	0.1 이하	Lighthouse CI
Lighthouse 성능 점수	90점 이상	Lighthouse CI

• 성능 예산은 프로젝트 초기에 수립하고, 팀 전체에 공유해야 합니다.
• 예산 초과 시 다음 절차를 따릅니다.
  1. 원인이 되는 코드 또는 리소스를 식별합니다.
  2. 코드 분할, 지연 로딩, 리소스 최적화 등의 개선 조치를 수행합니다.
  3. 개선 후 기준값 이내로 복귀했는지 검증합니다.
• 성능 예산 기준은 6개월 주기로 재검토하여 기술 환경 변화에 맞게 조정합니다.
• 재검토 시 실제 사용자 데이터(RUM)를 기반으로 기준값의 적정성을 평가합니다.