Bundle Analysis with @next/bundle-analyzer

The plain-language idea

@next/bundle-analyzer is an official Next.js plugin that wraps your build and produces a visual treemap of everything that ended up in your JavaScript bundles — one rectangle per module, sized proportionally to how many bytes it contributes. Instead of guessing which dependency is bloating the client bundle, you get an actual picture: a lodash import that isn't tree-shaking, a moment.js locale bundle nobody meant to include, a whole icon library pulled in for three icons.

It installs as a config wrapper around next.config.ts and only activates when you set an environment variable, so it never affects a normal build:

// next.config.ts
import type { NextConfig } from "next";
import createBundleAnalyzer from "@next/bundle-analyzer";

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

const nextConfig: NextConfig = {};

export default withBundleAnalyzer(nextConfig);

Running ANALYZE=true pnpm build then opens interactive treemaps in the browser — separate reports for the client bundle, the server bundle, and the edge runtime bundle — after the build finishes.

See it in a real thing: finding an accidental full-library import

ANALYZE=true pnpm build

Say the client treemap shows a single 180KB rectangle labeled date-fns — far bigger than expected for a "format one date" use case. The likely cause is an import like this:

// BAD: pulls in the entire date-fns package
import * as dateFns from "date-fns";

dateFns.format(new Date(), "PP");

// GOOD: only the functions actually used are bundled
import { format } from "date-fns";

format(new Date(), "PP");

The treemap doesn't fix anything by itself — it's a diagnostic. Once you can see that date-fns is disproportionately large, the fix is usually one of three things: switch to named imports so tree-shaking can drop the unused code, reach for optimizePackageImports in next.config.ts for packages with many named exports, or — if the whole thing is only needed behind an interaction, like a date picker that opens on click — wrap it in next/dynamic so it's not in the initial bundle at all.

What people usually miss

Watch out

• The analyzer only activates on a real production build (next build), not next dev. Dev-mode bundles are shaped completely differently (unminified, unbundled-by-route in places) and aren't representative of what ships to users.
• A big rectangle in the treemap isn't automatically a bug. A 150KB syntax highlighter used on every page of a docs site earning its size is different from the same 150KB sitting in a bundle for a page that never renders it — read the treemap alongside where the code is actually used.
• ANALYZE=true has to be set on the same command that runs the build, not exported separately in an unrelated shell session — a forgotten ANALYZE=true just produces a normal build with no report.
• The report is split into separate client, server, and edge treemaps. A dependency that's huge in the server bundle is not a user-facing performance problem the way the same size would be in the client bundle — server code never ships to the browser.
• Finding the big import is only step one. The analyzer tells you what is large; deciding whether to tree-shake the import, defer it with next/dynamic, or accept it because it's genuinely needed everywhere is a judgment call the tool doesn't make for you.

Why this matters in interviews

"Lighthouse flags a large JavaScript payload on your homepage — walk me through how you'd actually find what's causing it." tests whether a candidate has a real diagnostic workflow (run the analyzer, read the treemap, identify the specific offending import) versus guessing at optimizations blind, which is a common gap even among people who know next/dynamic exists as a fix.