Analyzing and Shrinking the Client Bundle
Use the bundle analyzer to find heavy dependencies and trim client JavaScript shipped to users.
Why Client Bundle Size Matters
Every kilobyte of JavaScript your app ships to users has a cost: download time, parse time, and execution time. On a mid-range mobile device on a 4G connection, a 1 MB JS bundle can add 3–5 seconds of blocking time before the page becomes interactive.
Next.js 15 with the App Router already does a lot for you:
- Server Components never ship to the client
- Route-based code splitting is automatic
- Tree shaking removes unused exports
But third-party libraries, accidental client imports, and large utility packages can silently inflate your bundle. This lesson shows you how to find and fix those problems systematically.
Installing @next/bundle-analyzer
The official Next.js bundle analyzer wraps webpack-bundle-analyzer and integrates cleanly with next.config.ts. Install it once as a dev dependency:
After installation, you wrap your Next.js config with the analyzer factory. It reads the ANALYZE environment variable so the report only opens when you explicitly request it — your normal builds are unaffected.
The analyzer generates two interactive HTML treemaps:
- client.html — JavaScript sent to the browser
- server.html — Node.js server bundle (useful but secondary)
// Terminal
// npm install --save-dev @next/bundle-analyzer
// next.config.ts
import type { NextConfig } from 'next';
import bundleAnalyzer from '@next/bundle-analyzer';
const withBundleAnalyzer = bundleAnalyzer({
enabled: process.env.ANALYZE === 'true',
openAnalyzer: true,
});
const nextConfig: NextConfig = {
// your existing config
};
export default withBundleAnalyzer(nextConfig);All lessons in this course
- Analyzing and Shrinking the Client Bundle
- Turbopack and Compiler Configuration Deep Dive
- Module Boundaries with server-only and client-only
- Dynamic Imports, Code Splitting, and Lazy Hydration