Bundle Analysis skill for Claude Code

Done well means: you know the compressed size of the initial JS per route, every large module in it is there on purpose, heavy features load on demand, the change is proven by before/after numbers from the same build, and a budget in CI stops the size creeping back.

Ground rules

• Measure compressed (gzip or brotli) size of what the browser downloads for the initial route. Raw minified size misleads; total dist/ size includes lazy chunks nobody loads.
• Work largest-first. Removing a 2 KB helper while a 300 KB charting library sits in the main chunk is noise.
• One change per measurement. Record the build command and the numbers.
• Do not trade bundle size for correctness: never drop polyfills the support matrix needs, never mark packages side-effect-free without checking.
• Budgets reference: aim for ≤ 150–200 KB compressed JS on the critical path for content and commerce pages on mid-range mobile; app shells can justify more, but the number should be a decision, not an accident.

Workflow

- [ ] 1. Baseline: production build, record compressed sizes per entry/route
- [ ] 2. Visualize: generate a treemap and list the top 10 modules in initial chunks
- [ ] 3. Classify each: needed now / needed later / duplicated / not needed
- [ ] 4. Fix in order: remove > lazy-load > replace > tree-shake > target modern browsers
- [ ] 5. Rebuild and compare against the baseline
- [ ] 6. Add or tighten a CI budget

1. Baseline

node scripts/check_bundle_budget.mjs dist --compression brotli --top 15

The script walks a build directory, prints gzip or brotli sizes per file (largest first) and a total, and exits 1 when --max-total-kb, --max-file-kb, or a per-pattern --budget "assets/index-*.js=120" is exceeded. Use --json to store a baseline.

Framework build outputs also print sizes: next build shows per-route first-load JS; vite build prints gzip sizes per chunk.

2. Visualize

Bundler	Analyzer
Vite / Rollup	rollup-plugin-visualizer in the config (visualizer({ open: true, gzipSize: true, brotliSize: true })), or npx vite-bundle-visualizer
webpack	webpack-bundle-analyzer plugin, or webpack --profile --json > stats.json then npx webpack-bundle-analyzer stats.json
Next.js	@next/bundle-analyzer wrapped around next.config, run with ANALYZE=true next build (webpack builds); for Turbopack builds check the installed Next version’s analyzer docs
esbuild	--metafile=meta.json, then upload to the esbuild bundle analyzer page or inspect with esbuild --analyze
Any (with source maps)	npx source-map-explorer 'dist/assets/*.js'

Look for: one dependency dominating a chunk, the same library twice (two versions or CJS + ESM copies), locale or icon packs bundled whole, server-only code in client chunks, and polyfills for browsers you do not support.

Why is this module here? webpack: stats.json reasons; Vite/Rollup: the visualizer’s importer tree; any bundler: grep -rn "from 'heavy-lib'" src to find import sites.

3–4. Fix patterns, highest value first

Finding	Fix
Unused dependency or dead code	Remove it; find candidates with npx knip
Heavy feature not needed at first paint (editor, charts, maps, PDF, date pickers)	Dynamic import() at the interaction or route boundary
Whole library imported for one function	Named imports from ESM builds; or native API
Duplicate versions	npm ls <pkg> / pnpm why <pkg>; dedupe with npm dedupe, overrides/resolutions
Moment.js, full lodash, big icon sets	date-fns or Intl/Temporal; lodash-es per-function or native; per-icon imports
Locale data bundled	Load only the active locale dynamically
CJS dependency defeating tree shaking	Prefer a package with an ESM build; check its exports/module fields
Barrel file (index.ts re-exporting everything) pulling the world in	Import from the specific module path; in Next.js use experimental.optimizePackageImports for listed libraries
Legacy polyfills and transpilation	Update browserslist to the real support matrix; drop core-js entries not needed
Server code in client bundle	Move behind server-only modules (import "server-only" in Next.js), split shared utils

Route and interaction splitting:

// React: route-level
import { lazy, Suspense } from "react";
const Reports = lazy(() => import("./routes/Reports"));

<Suspense fallback={<Spinner />}><Reports /></Suspense>

// Interaction-level: load on intent
async function openEditor() {
  const { createEditor } = await import("./editor");   // separate chunk
  createEditor(el);
}
button.addEventListener("pointerenter", () => import("./editor"), { once: true }); // prefetch on hover

// Next.js client component that should not be in first-load JS
import dynamic from "next/dynamic";
const Chart = dynamic(() => import("../components/Chart"), { ssr: false, loading: () => <ChartSkeleton /> });

Tree shaking requirements:

• The library ships ES modules and declares "sideEffects": false (or a list) in its package.json. For your own packages in a monorepo, add the field truthfully: files that register globals or import CSS are side effects.
• Use named imports: import { debounce } from "lodash-es", not import _ from "lodash".
• Avoid export * from chains in app code; they make side-effect analysis harder and slow dev servers.
• Check the result in the treemap, not by assumption.

Manual chunking (build.rollupOptions.output.manualChunks in Vite, splitChunks in webpack) is a last resort for caching vendor code; it rarely reduces what the initial route downloads and can make it worse.

5. Compare

Rebuild with the same command and compare totals and the initial-route number:

node scripts/check_bundle_budget.mjs dist --compression brotli --json > after.json

Also confirm behavior: lazy chunks load when expected (DevTools Network, filter JS), and no new waterfall delays the main interaction (a lazy chunk needed immediately after load should be preloaded or kept in the main bundle).

6. Budgets in CI

node scripts/check_bundle_budget.mjs dist --compression gzip \
  --budget "assets/index-*.js=120" --budget "assets/vendor-*.js=90" --max-file-kb 150

Alternatives if the project already uses them: size-limit (with .size-limit.json, reports in PRs) or bundler-native warnings (build.chunkSizeWarningLimit in Vite, performance.maxEntrypointSize in webpack). Set budgets just above the current size after the cleanup, then ratchet down.

Choosing replacements

Before adding a dependency, check its cost with the package’s published size (e.g. pkg-size.dev or bundlephobia) and whether a platform API covers it:

Need	Platform option
Date formatting	Intl.DateTimeFormat, Intl.RelativeTimeFormat
Number/currency	Intl.NumberFormat
Deep clone	structuredClone
UUID	crypto.randomUUID()
HTTP client	fetch
Class names joiner	clsx (tiny) or template strings
Animation basics	CSS transitions, Web Animations API

Gotchas

• sideEffects: false on a package that imports CSS or registers polyfills silently drops them in production; test the built app.
• Dynamic import() with a fully variable path bundles every file the bundler can match; keep the path static or with a constrained template.
• Source-map-based tools attribute inlined helpers oddly; cross-check with the bundler’s own stats.
• Gzip numbers from your laptop may differ slightly from the CDN’s compression level; compare relatively, not to the byte.
• Lazy-loading something every user needs on first interaction just moves the cost into INP. Preload it after first paint instead.
• CSS counts too: unused framework CSS and large icon fonts block render.

Report template

**Build:** `pnpm build` (Vite 6), brotli sizes
**Initial route JS:** 412 KB -> 186 KB
**Changes:**
1. Charting lib (138 KB) moved behind dynamic import on /reports — loads on route entry
2. moment + locales (71 KB) replaced with Intl.DateTimeFormat
3. Duplicate react-dom copies removed via pnpm override (18 KB)
**Budget added:** index-*.js <= 200 KB brotli in CI
**Checked:** /reports chart renders, no new request waterfall on home