Bundle analysis and budgets: first-load JS, barrel-file bloat, and CI gates

Reading the numbers: first-load JS and the analyzer treemap

Every next build prints the table that matters: per route, its own size and its First Load JS — the total JavaScript a cold visitor downloads to render that route, which is the route’s own chunk plus the shared chunks (framework, your common code) listed at the bottom as “First Load JS shared by all”. A fresh create-next-app starts at roughly 100 KB gzipped of shared first-load; that’s your floor. The route column going up hurts one page — the shared number going up hurts every page at once, which is why the Hook’s icon import was a site-wide incident, not a header tweak.

When the table tells you that something grew, @next/bundle-analyzer tells you what:

// next.config.mjs
import bundleAnalyzer from "@next/bundle-analyzer";

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === "true",
});

export default withBundleAnalyzer({
  // your existing config
});

ANALYZE=true next build emits interactive treemaps (client, plus the server and edge bundles). Read the client treemap and mind the units: stat is raw module size, parsed is what the browser must actually parse and execute after minification, gzipped is what crosses the network. Network cost reads from gzip; main-thread cost reads from parsed — a chunk that gzips to 90 KB can be 350 KB parsed, and the phone pays the parsed price. The diagnostic move is always the same: find the unexpectedly large rectangle, check which chunk it sits in (shared vs route), and trace which import dragged it there.

What actually inflates bundles

Three mechanisms account for most real-world bloat. First, barrel files — index.ts re-exporting an entire package. Importing one icon from a 900-export barrel forces the bundler to resolve and analyze every module behind it, and anything not provably side-effect-free survives tree-shaking into your chunk; icon and component libraries are the classic +300 KB single import. Next ships a targeted fix: optimizePackageImports in next.config, which rewrites barrel imports into direct per-module imports at build time — enabled by default for a list of known-huge libraries (lucide-react, @mui/icons-material, date-fns and friends), and worth adding your internal design-system package to, because your own barrels get no special treatment.

Second, client-component creep. 'use client' marks a boundary, not a component: everything it imports — and everything those import — joins the client graph and ships to the browser. One 'use client' placed high (a layout wrapper, a providers file that also imports utilities) silently converts a server-only subtree into shipped JavaScript. The bundle-shaped symptom: libraries you “only use on the server” appearing in the client treemap, because some client boundary transitively reached them. Third, the heavyweight dependency chosen casually: a charting library on a route where a sparkline would do, a 70 KB date library where Intl would do, lodash imported whole. Audit these in the treemap from largest rectangle down — the top five usually account for more than half the parsed bytes.

The chain from kilobytes to Core Web Vitals

Budgets only get defended when the team believes the causal chain, so make it explicit. Gzipped bytes cost the network; then the phone parses and executes the parsed bytes on the main thread. A mid-range Android executes JavaScript several times slower than the laptop it was reviewed on — an extra 300 KB parsed is roughly an extra second of main-thread work on such a device. That second lands in two places. During load, script evaluation and hydration compete with everything else; long tasks pile up, and any tap during that window waits — which is how JS weight degrades INP, whose “good” threshold is 200 ms at p75. Before that, the bytes themselves compete with the LCP image and critical CSS for bandwidth, and on script-rendered content LCP can’t even paint until execution finishes — the path from chunk size to a blown 2.5 s LCP. CLS completes the triad at 0.1, though its causes live mostly in the previous two lessons. The summary worth pinning to the team wiki: gzip costs the network, parsed costs the main thread, and the main thread is where INP lives.

Budgets in CI: making the number owned

A budget is a number with a build-breaker attached. The mechanics are simple — what matters is which numbers. Gate per-route first-load JS, not total build output: total grows legitimately with every new route, while a route’s first-load growing means real users on that page pay more. A practical starting posture: shared first-load ≤ 130 KB gz, heaviest route ≤ 200 KB gz, and a per-PR delta rule — any route growing by more than ~10 KB needs a justification in the PR description. Tools: size-limit pointed at the built chunks, a script that parses next build’s output JSON and compares against a checked-in budgets.json, or the analyzer artifact uploaded on every PR so the treemap diff is one click away in review.

Two operational details separate budgets that work from budgets that rot. Ratchet, don’t aspire: set the initial budget to current reality plus ~5%, then tighten as you win bytes back — a budget set at the aspirational number on day one is red forever and gets ignored by sprint two. And make the failure actionable: the CI message should name the route, the delta, and the top new modules (the analyzer JSON has them), because “bundle check failed” trains people to bump the budget, while “shared chunk +303 KB: @acme/icons via Header.tsx” trains them to fix the import. Together these two details decide whether a budget is a discipline tool or a bureaucratic checkbox: the ratchet gives it credibility (it can be hit), the actionable message gives it teeth (fixing is easier than bumping). The Hook’s incident, replayed with this gate, dies in review as a red check on a two-line PR — which is the entire point: the budget converts a quarter of degraded field data into a thirty-second code review comment.