Next.js Bundle Analyzer: Finding and Fixing Size Issues

Why Your Next.js App Is Slower Than It Should Be

Honestly, most Next.js apps ship way more JavaScript than they need to. You add a date picker, a charting library, maybe a rich text editor — and six months later your first-load JS is sitting at 900kB and nobody's sure why.

The thing is, Next.js does a lot of automatic optimization out of the box. Code splitting per route, React Server Components, image optimization — it's all there. But it can't save you from yourself when you import moment.js to format a single date string, or when you pull in all of lodash for one debounce call.

That's exactly where @next/bundle-analyzer comes in. It gives you a visual treemap of every module in your client bundles, broken down by size. Once you see it, you can't unsee it. That 400kB chunk labeled node_modules/some-animation-library hits differently when it's rendered as a giant purple rectangle taking up half your screen.

Installing and Configuring @next/bundle-analyzer

Setup takes about two minutes. Install the package, wrap your Next.js config, and you're done.

npm install --save-dev @next/bundle-analyzer

Then in your next.config.js (or next.config.ts if you're on Next.js 15+): ``js // next.config.js const withBundleAnalyzer = require('@next/bundle-analyzer')({ enabled: process.env.ANALYZE === 'true', }); /** @type {import('next').NextConfig} */ const nextConfig = { // your existing config }; module.exports = withBundleAnalyzer(nextConfig); ` Then add a script to your package.json: `json { "scripts": { "analyze": "ANALYZE=true next build" } } ` Run npm run analyze` and it'll open two browser tabs — one for the client bundle, one for the server bundle. The client one is almost always the interesting one.

Reading the Treemap: What You're Actually Looking At

The treemap is organized by bundle chunk. Each rectangle represents a module or group of modules. Bigger rectangle = more bytes. The color coding groups things by chunk, not by size category, so don't read too much into the colors.

What you're hunting for are large rectangles inside node_modules. Your own application code is usually tiny compared to dependencies. If you see react-pdf, recharts, @aws-sdk, or similar sitting there at 200kB+ each, those are your targets.

There's a gzip toggle in the top-left corner. Always check both views. A library might be 500kB parsed but compress down to 90kB gzipped — still significant, but the actual network transfer cost is the gzipped number. The parsed size matters for parse and execution time on lower-end devices.

The Most Common Bundle Killers (and How to Fix Them)

Some patterns show up over and over again. Moment.js is the classic offender — it pulls in all locale data by default, adding roughly 232kB parsed. Swap it for date-fns (import individual functions, ~2-5kB per function) or the native Intl.DateTimeFormat API if you don't need heavy formatting.

Lodash is another one. If you're doing import _ from 'lodash' you're loading the entire 70kB library. Use named imports with lodash-es instead: import { debounce } from 'lodash-es'. Tree-shaking will do its job and you'll end up with maybe 3kB.

Icon libraries deserve special attention. react-icons is great but if you import from the top-level barrel: import { FiCheck, FiX } from 'react-icons/fi' — that's actually fine, each sub-path like /fi is its own module. What kills you is import * as Icons from 'react-icons'. Same story with @mui/icons-material. Always import from the specific icon path.

Heavy charting libraries like recharts or chart.js should almost always be lazy-loaded. If the chart only appears after a user interaction or on a specific route, there's no reason to put it in the initial bundle. Use next/dynamic with ssr: false and you'll shave 200-300kB off your first-load JS.

Dynamic Imports and Code Splitting in Next.js

Next.js splits code at the route level automatically, but that's not always enough. Components that are conditionally rendered, modals, heavy UI widgets — those are all candidates for dynamic import.

import dynamic from 'next/dynamic';

// Heavy chart component — only loads when rendered
const SalesChart = dynamic(() => import('@/components/SalesChart'), {
  ssr: false,
  loading: () => <div className="h-64 bg-gray-100 animate-pulse rounded-lg" />,
});

// Modal that only opens on user action
const SettingsModal = dynamic(() => import('@/components/SettingsModal'), {
  ssr: false,
});

export default function Dashboard() {
  const [showSettings, setShowSettings] = useState(false);

  return (
    <div>
      <SalesChart />
      {showSettings && <SettingsModal onClose={() => setShowSettings(false)} />}
    </div>
  );
}

The loading prop is worth spending time on. A skeleton that matches your component's dimensions prevents layout shift while the chunk loads. If you're already using component libraries or working with visual styles from tools like glassmorphism generator or gradient generator, you can match the skeleton to your design system's color palette easily.

Analyzing Server vs Client Bundles

The analyzer opens two tabs: client.html and server.html. Most performance advice focuses on the client bundle, and for good reason — that's what gets shipped to the browser. But the server bundle matters too for cold start time, especially if you're on serverless functions.

Server bundle issues are usually large utility libraries imported in API routes or server components. Things like aws-sdk (use the modular v3 packages: @aws-sdk/client-s3 instead of the full SDK), heavy ORMs with all plugins loaded, or PDF generation libraries that get imported in a route that only runs occasionally.

Worth noting: React Server Components (available properly since Next.js 13.4+) let you keep large data-fetching dependencies entirely server-side. They never touch the client bundle at all. If you're on an older pattern — API routes plus client-side fetching — migrating data-heavy components to RSC can dramatically reduce what ends up in the client treemap. Is it always worth the refactor? Depends on your app's architecture, but it's worth measuring.

Setting a Bundle Size Budget

Finding problems once is fine. Preventing them from coming back is the actual goal. You can set a size budget in Next.js that will warn (or error) during build when bundles exceed a threshold.

// next.config.js
const nextConfig = {
  experimental: {
    // Warn when a page's JS exceeds this size (in kB)
  },
  // Built-in: Next.js warns when First Load JS > 130kB by default
  // You can also use bundlePagesRouterDependencies for Pages Router
};
```

For more control, `bundlesize` or `size-limit` as a CI step is the move:

```json
// package.json — using size-limit
{
  "size-limit": [
    {
      "path": ".next/static/chunks/pages/index-*.js",
      "limit": "120 kB"
    }
  ],
  "scripts": {
    "size": "size-limit"
  }
}

Pair this with your CI pipeline and you've got a hard gate preventing bundle regressions. When someone adds a new dependency that pushes the homepage bundle over your limit, the build fails and the PR can't merge without a conscious decision to raise the budget or find an alternative. That's the kind of guardrail that actually sticks.

If your UI relies on visual effects like shadows or complex CSS — check out our guides on Tailwind shadows generator and box shadow CSS guide for CSS-only approaches that add zero kB to your JavaScript bundle.

Practical Checklist Before Your Next Deploy

Run npm run analyze and open the client treemap. Are any individual modules above 100kB? Write them down. Check if there are duplicate versions of the same library — sometimes you end up with react-dom 18.2.0 AND 18.3.0 in the same bundle because two packages have conflicting peer deps.

Use npm ls <package-name> to trace where a dependency comes from. Use webpack-bundle-analyzer's search box (top right) to find specific modules. Run next build and look at the route-by-route First Load JS table in the terminal — Next.js prints it automatically, and anything over ~130kB on a route that should be lightweight is a red flag.

Finally, don't optimize everything at once. Pick the two or three biggest wins from your treemap, fix those, measure the result, then move on. Chasing every kB at once leads to over-engineered lazy loading of things that don't matter. The 400kB date library you removed is worth ten times more than micro-optimizing a 4kB utility you wrote yourself.

FAQ

Read next