{"id":20232,"library":"next-bundle-analyzer","title":"next-bundle-analyzer","description":"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.","status":"active","version":"0.6.8","language":"javascript","source_language":"en","source_url":"https://github.com/josselinbuils/next-bundle-analyzer","tags":["javascript","Next","Next.js","bundle","analyzer","performance","modules","size","typescript"],"install":[{"cmd":"npm install next-bundle-analyzer","lang":"bash","label":"npm"},{"cmd":"yarn add next-bundle-analyzer","lang":"bash","label":"yarn"},{"cmd":"pnpm add next-bundle-analyzer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to run; must be installed separately (Next.js 10-14).","package":"next","optional":false}],"imports":[{"note":"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.","wrong":"import withNextBundleAnalyzer from 'next-bundle-analyzer';","symbol":"default","correct":"const withNextBundleAnalyzer = require('next-bundle-analyzer');"},{"note":"The function returned by require() is the plugin factory; you must invoke it with options immediately (or pass directly to the wrapper).","wrong":"const withNextBundleAnalyzer = require('next-bundle-analyzer'); withNextBundleAnalyzer({ enabled: true });","symbol":"withNextBundleAnalyzer (function)","correct":"const withNextBundleAnalyzer = require('next-bundle-analyzer')({ enabled: true });"},{"note":"TypeScript types are shipped but only for static analysis; PluginOptions is not a runtime export.","wrong":"const { PluginOptions } = require('next-bundle-analyzer');","symbol":"type PluginOptions","correct":"import type { PluginOptions } from 'next-bundle-analyzer';"}],"quickstart":{"code":"// next.config.js\nconst shouldAnalyzeBundles = process.env.ANALYZE === 'true';\n\nlet nextConfig = {\n  // your Next.js config\n};\n\nif (shouldAnalyzeBundles) {\n  const withNextBundleAnalyzer = require('next-bundle-analyzer')({\n    enabled: true,\n    clientOnly: false,\n    format: 'html',\n    reportDir: 'analyze',\n    reportFilename: 'bundles'\n  });\n  nextConfig = withNextBundleAnalyzer(nextConfig);\n}\n\nmodule.exports = nextConfig;","lang":"javascript","description":"Conditionally enables bundle analysis via ANALYZE environment variable, generating HTML reports for both client and server bundles."},"warnings":[{"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.","message":"Accidentally leaving the plugin enabled in production","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Explicitly set clientOnly: false if you want reports for both client and server bundles.","message":"clientOnly option defaults to true - may miss server-side bundle analysis","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade to next-bundle-analyzer@0.6.8 or later to support Next.js 14.","message":"peer dependency next@14 support added in v0.6.8","severity":"deprecated","affected_versions":"<0.6.8"},{"fix":"If you rely on the old grouping logic, update your report interpretation or pin to v0.5.x.","message":"v0.6.0 changed how groups are reported: 'shared by all pages' vs 'shared by multiple pages'","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Ensure the output path in Next.js config is set correctly; reportDir is appended to that path.","message":"reportDir is relative to Webpack output path, not project root","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade to v0.6.5 or later for improved tooltip positioning.","message":"Tooltip position may be incorrect in some cases (fixed in v0.6.5)","severity":"gotcha","affected_versions":"<0.6.5"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: npm install -D next-bundle-analyzer. Use conditional require as shown in the quickstart.","cause":"Package not installed, or installed as dev dependency but required without conditional guard in production (where devDeps might be missing).","error":"Cannot find module 'next-bundle-analyzer'"},{"fix":"Use require() instead of import: const withNextBundleAnalyzer = require('next-bundle-analyzer');","cause":"Using ESM import syntax in next.config.js which is typically CommonJS.","error":"Module parse failed: Unexpected token (1:0) in next.config.js"},{"fix":"Ensure you require the package and immediately invoke it with an options object: require('next-bundle-analyzer')({ ... })","cause":"The plugin was invoked incorrectly, e.g., withNextBundleAnalyzer is not a function or called with wrong arguments.","error":"Cannot read properties of undefined (reading 'webpack')"},{"fix":"Downgrade Next.js to v14 or wait for a version bump in next-bundle-analyzer.","cause":"Peer dependency only supports Next.js 10-14.","error":"Next.js version 15 is not supported"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}