next-bundle-analyzer

0.6.8 verified Sat Apr 25 auth: no javascript

A customized Webpack Bundle Analyzer wrapper for Next.js that generates per-page chunk reports, differentiating between shared and page-specific bundles. Currently at version 0.6.8, it supports Next.js 10-14 as a peer dependency. Unlike @next/bundle-analyzer, this library provides detailed group analysis (shared across all pages vs shared by multiple pages) and per-page issuer information. It generates HTML or JSON reports with configurable output directory and filename. Active development with periodic releases fixing tooltips, compatibility, and dependency updates.

Common errors

error Cannot find module 'next-bundle-analyzer' ↓

cause Package not installed, or installed as dev dependency but required without conditional guard in production (where devDeps might be missing).

fix

Ensure the package is installed: npm install -D next-bundle-analyzer. Use conditional require as shown in the quickstart.

error Module parse failed: Unexpected token (1:0) in next.config.js ↓

cause Using ESM import syntax in next.config.js which is typically CommonJS.

fix

Use require() instead of import: const withNextBundleAnalyzer = require('next-bundle-analyzer');

error Cannot read properties of undefined (reading 'webpack') ↓

cause The plugin was invoked incorrectly, e.g., withNextBundleAnalyzer is not a function or called with wrong arguments.

fix

Ensure you require the package and immediately invoke it with an options object: require('next-bundle-analyzer')({ ... })

error Next.js version 15 is not supported ↓

cause Peer dependency only supports Next.js 10-14.

fix

Downgrade Next.js to v14 or wait for a version bump in next-bundle-analyzer.

Warnings

gotcha Accidentally leaving the plugin enabled in production ↓

fix Conditionally require the plugin based on an environment variable (e.g., process.env.ANALYZE) to avoid analysis overhead and potential report leakage in production.

gotcha clientOnly option defaults to true - may miss server-side bundle analysis ↓

fix Explicitly set clientOnly: false if you want reports for both client and server bundles.

deprecated peer dependency next@14 support added in v0.6.8 ↓

fix Upgrade to next-bundle-analyzer@0.6.8 or later to support Next.js 14.

breaking v0.6.0 changed how groups are reported: 'shared by all pages' vs 'shared by multiple pages' ↓

fix If you rely on the old grouping logic, update your report interpretation or pin to v0.5.x.

gotcha reportDir is relative to Webpack output path, not project root ↓

fix Ensure the output path in Next.js config is set correctly; reportDir is appended to that path.

gotcha Tooltip position may be incorrect in some cases (fixed in v0.6.5) ↓

fix Upgrade to v0.6.5 or later for improved tooltip positioning.

Install

npm install next-bundle-analyzer

yarn add next-bundle-analyzer

pnpm add next-bundle-analyzer

Imports

default
wrong
```
import withNextBundleAnalyzer from 'next-bundle-analyzer';
```
correct
```
const withNextBundleAnalyzer = require('next-bundle-analyzer');
```
ESM import may work in some setups but CommonJS require is recommended for next.config.js. The default export is a function that takes options.

withNextBundleAnalyzer (function)

wrong

const withNextBundleAnalyzer = require('next-bundle-analyzer'); withNextBundleAnalyzer({ enabled: true });

correct

const withNextBundleAnalyzer = require('next-bundle-analyzer')({ enabled: true });

The function returned by require() is the plugin factory; you must invoke it with options immediately (or pass directly to the wrapper).

type PluginOptions
wrong
```
const { PluginOptions } = require('next-bundle-analyzer');
```
correct
```
import type { PluginOptions } from 'next-bundle-analyzer';
```
TypeScript types are shipped but only for static analysis; PluginOptions is not a runtime export.

Quickstart

Conditionally enables bundle analysis via ANALYZE environment variable, generating HTML reports for both client and server bundles.

// next.config.js
const shouldAnalyzeBundles = process.env.ANALYZE === 'true';

let nextConfig = {
  // your Next.js config
};

if (shouldAnalyzeBundles) {
  const withNextBundleAnalyzer = require('next-bundle-analyzer')({
    enabled: true,
    clientOnly: false,
    format: 'html',
    reportDir: 'analyze',
    reportFilename: 'bundles'
  });
  nextConfig = withNextBundleAnalyzer(nextConfig);
}

module.exports = nextConfig;