Bundle analysis is detective work. Start with a visualization, find the surprises, fix the biggest ones, repeat.

Step 1: get a visual

Run once. Open the treemap. You're looking for:

1. Unexpectedly large nodes — moment (200KB), lodash (75KB if you imported the namespace), pdfjs, mapbox-gl.
2. Duplicates — two copies of React, two copies of a util lib from peer-dep mismatches.
3. Mega-chunks — one chunk holds everything; means split points aren't doing their job.
4. Polyfills you don't need — core-js for IE11 in a modern-only app.

Step 2: common fixes (highest ROI first)

Replace heavy deps with smaller equivalents:

• moment (~290KB) → date-fns (tree-shakeable, ~10–30KB used) or dayjs (~7KB).
• lodash full import → lodash-es per-function imports, or native ES (Array.prototype.flat, structuredClone).
• Big icon set (mdi, fontawesome) → import per icon, or use lucide-react with tree-shaking.
• axios → native fetch (if you don't need its features).

Per-function imports:

// Bad — pulls in all of lodash
import _ from 'lodash';
_.debounce(fn, 100);

// Good — only debounce ships
import debounce from 'lodash-es/debounce';

For libraries that don't tree-shake well, configure modular imports in Next:

// next.config.js
modularizeImports: {
  lodash: { transform: 'lodash/{{member}}' },
}

Deduplicate:

npm ls react       # any duplicates?
npm dedupe

Peer-dep mismatches are a common cause. overrides (npm) / resolutions (yarn) can force one version.

Code-split heavy widgets:

const Chart = dynamic(() => import('./Chart'), { ssr: false });

Externalize big polyfills:

If you only need Intl in 1% of locales, dynamic-import the polyfill instead of bundling.

Tree-shaking checks:

• Library has "sideEffects": false in its package.json? Tree-shaking works.
• Importing CSS as a side effect (import './foo.css')? Mark it in sideEffects.
• Using require? Webpack/esbuild can't always tree-shake CommonJS.

Step 3: budget + CI guard

Set a budget. Fail the build if a chunk grows beyond it.

Webpack:

performance: {
  maxAssetSize: 200_000,
  maxEntrypointSize: 300_000,
  hints: 'error',
}

Next: @next/bundle-analyzer in CI + a script that parses the manifest and fails if specific routes exceed a budget.

Use size-limit as a stack-agnostic CI guard:

"size-limit": [
  { "path": ".next/static/chunks/main-*.js", "limit": "150 KB" }
]

A budget is the single most important tool — without one, regressions sneak in PR by PR until someone runs an analyzer and finds a 2MB main chunk.

Step 4: ongoing hygiene

• Quarterly dependency audit: any unused deps (depcheck)?
• Bundlephobia.com on new deps before adding.
• Pin React Server Components (Next App Router) so server-only code doesn't ship to client.
• Use 'use client' boundaries deliberately — every client component is a JS handoff.
• Audit node_modules size occasionally — sometimes a dev dep accidentally became a runtime dep.

What to ignore

• Tiny shavings (saving 2KB in a 300KB bundle isn't worth a refactor).
• Theoretical wins that don't move LCP/INP — real metrics are the goal, not the analyzer.
• Aggressive splitting on the critical path — too many tiny chunks hurt.

Mental model

A bundle is a budget. Spend it on code that runs above the fold; defer the rest. The first 200KB of JS roughly maps to time-to-interactive on mid-range mobile — anything beyond that needs justification.