Bundle Size Analysis

Quick Reference

Capability Tiers

This skill operates at different capability levels depending on available data:

See references/capability-tiers.md for details.

CRITICAL: Agent Claim Constraints

These rules are NON-NEGOTIABLE. Violating them produces hallucinations.

Tier A/B (Default - No stats.json)

ALLOWED claims:

• •"Total JS is 245KB gzipped"
• •"The largest chunk is vendor-abc123.js at 118KB"
• •"Initial load includes 3 entry chunks totaling 89KB"
• •"Bundle increased 12KB (+5%) from baseline"
• •"New file vendor-forms-xyz.js appeared in this build"

FORBIDDEN claims:

• •"lodash contributes 40KB to the bundle"
• •"Replace moment.js with dayjs to save 30KB"
• •"The zod package is responsible for the increase"
• •"date-fns accounts for 15% of vendor chunk"

When asked about package attribution:

"To identify package-level contribution, open dist/stats.html for an interactive treemap, or enable Rollup stats output in vite.config.ts for programmatic analysis."

On Regressions

ALLOWED:

• •Report the delta (bytes and percent)
• •List new/removed/changed files
• •Reference commit diff if available

FORBIDDEN:

• •Guess the cause without evidence
• •Attribute to specific code changes without seeing the diff
• •Claim a package caused the regression

When cause is uncertain:

"Bundle increased by X KB. To identify the cause, review the commit diff or open dist/stats.html to compare module sizes."

Existing Scripts

scripts/check-budgets.cjs

Per-bundle budget enforcement. Reads .size-limit.json configuration.

node scripts/check-budgets.cjs
# Exit 0 = pass, Exit 1 = budget exceeded

scripts/size-report.mjs

Reports top 10 largest assets by gzip size.

node scripts/size-report.mjs
# Outputs table to stdout

scripts/compare-bundle-size.js

Compares current build to baseline artifact. Used in CI.

node scripts/compare-bundle-size.js --base baseline.json --head current.json

scripts/size-first-load.mjs

Reports the initial load bundle size (entry chunks only).

node scripts/size-first-load.mjs
# Outputs initial load size

CI Integration

The existing workflow .github/workflows/bundle-size-check.yml:

1. •Downloads baseline artifact from main branch
2. •Builds PR branch
3. •Compares sizes
4. •Posts PR comment with delta
5. •Fails if budget exceeded (unless approved:perf-budget-change label applied)

Troubleshooting

See references/troubleshooting.md for common issues:

• •Manifest not found
• •Baseline unavailable
• •Budget configuration errors

Enabling Tier C (Package Attribution)

To unlock package-level attribution, add Rollup stats output:

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

export default defineConfig({
  plugins: [
    visualizer({
      filename: 'dist/stats.json',
      json: true,  // Enable JSON output
    }),
  ],
});

WARNING: This increases build time. Only enable if package attribution is regularly needed.