webpack-bundle-analyzer

webpack-bundle-analyzer is a webpack plugin and companion CLI utility that renders the contents of your webpack output as an interactive, zoomable treemap. Rather than trusting webpack’s raw stats output, it parses the actual emitted bundle files (when given the output directory) to compute real per-module sizes, and reports them across four different measures at once: stat size (pre-minification), parsed size (post-minification), and gzip/Brotli/Zstandard compressed size — so you can tell the difference between a module that looks huge in source and one that’s actually costing you bytes over the wire.

It runs in three modes: server starts a local HTTP server with a live-updating report (pushed over WebSocket on every rebuild), static writes a single self-contained HTML report you can archive or attach to a CI artifact, and json dumps the same chart data as raw JSON for custom tooling. The CLI path works directly against a webpack --json stats file when you don’t want to touch the build config at all. The treemap itself is searchable, supports per-chunk filtering via a sidebar and right-click context menu, and distinguishes initial vs. lazy-loaded chunks per entrypoint — making it the de facto way developers in the webpack ecosystem answer “why is my bundle this big.”

What You Get

• An interactive, zoomable treemap UI (built with Preact, MobX, and the FoamTree treemap library) rendered either in a live local server or as a static HTML file you can share
• Real per-module size measurements across five metrics — stat, parsed, gzip, Brotli, and Zstandard — computed by actually parsing the emitted bundle source, not just trusting webpack’s stats file
• A CLI utility (webpack-bundle-analyzer <stats.json>) that works entirely from a webpack stats file, with no plugin wiring required
• Live-updating reports over WebSocket in server mode, so the treemap refreshes automatically on every rebuild during development
• Chunk-level filtering via a sidebar and right-click context menu, plus visibility into which chunks are part of each entrypoint’s initial load vs. lazily loaded later

Common Use Cases

• Diagnosing why a production bundle suddenly grew after adding a new dependency
• Finding accidentally duplicated or unexpectedly large third-party modules bundled into client code
• Auditing initial-load JS per entrypoint to cut time-to-interactive on a marketing or app shell page
• Generating a static bundle report as a CI artifact to track size regressions over time
• Verifying that code-splitting and lazy-loading configuration actually moved modules out of the initial chunk

Under The Hood

Architecture

The plugin entry point (BundleAnalyzerPlugin) hooks into compiler.hooks.done (falling back to the legacy compiler.plugin('done') API for webpack 4) and, on each build, dispatches to one of three action paths keyed off analyzerMode: starting a live server, writing a static HTML report, or emitting a json dump — all funneled through viewer.js. That module resolves report options and calls into analyzer.js, the core data-processing layer, which normalizes webpack’s stats shape (including edge cases like data hiding in a children array), builds a per-asset module tree via a Folder/Module/ContentModule/ConcatenatedModule class hierarchy under src/tree/, and augments each module with a real parsed size by statically parsing the emitted bundle source. In server mode, sirv serves static UI assets while a ws WebSocket channel pushes updated chart data to the browser on every rebuild; static mode instead renders the same chart data into a single self-contained HTML file via template.js. A separate Preact + MobX single-page app under client/ (its own store.js MobX store, Treemap.jsx wrapping the third-party FoamTree charting library, plus Sidebar/Search/ContextMenu components) consumes that chart data — giving a clean pipeline from webpack hook through stats normalization, module-tree construction, and size computation to a shared UI regardless of output mode.

Tech Stack

The analyzer half runs on plain Node.js (>=20.9) with a deliberately small dependency set: @discoveryjs/json-ext for streaming/chunked parsing of large stats files, acorn/acorn-walk for statically parsing bundled JS to recover real module boundaries, commander for the CLI, sirv for static file serving, ws for the WebSocket push channel, and picocolors for console output. The client is a separate Preact 10 + MobX 6 single-page app built with its own webpack.config.js (babel-loader, css-loader, postcss-loader/autoprefixer, cssnano for production CSS), rendering its treemap through the commercially-licensed @carrotsearch/foamtree library. The src/ build itself goes through Babel (@babel/preset-env/preset-react, class-properties and runtime plugins), tests run on Jest 30 with Puppeteer for dev-server/browser-driven cases, and releases are managed with Changesets.

Code Quality

The repo carries an extensive fixture-driven test suite: alongside unit tests for the plugin, viewer/server, and stats-parsing utilities, test/stats/ holds dozens of real webpack-stats fixtures covering edge cases — missing chunks, invalid dynamic imports, worker-loader output, multiple entrypoints, module concatenation, special characters in filenames — so regressions in stats-shape handling get caught directly rather than through incidental coverage. Error handling favors explicit, leveled logging over hard failures: viewer.js catches analyzer errors and reports them through a Logger instead of crashing the host webpack build, and bundle-asset parse failures are caught per-asset with a distinguishing message (ENOENT vs. a generic parse error) so one bad asset doesn’t sink the whole report. The codebase is plain JavaScript annotated throughout with JSDoc types and validated in strict mode via tsc --noEmit (checkJs), giving real type safety without a separate TypeScript build step, and both ESLint (eslint-config-webpack) and Prettier are enforced through dedicated lint/format scripts backed by GitHub Actions CI.

API Design The public surface is intentionally minimal on both entry points: new BundleAnalyzerPlugin(opts) needs zero arguments to do something useful out of the box (defaulting to server mode with auto-open enabled), and the CLI mirrors the same option set one-for-one so switching between plugin config and command-line flags requires no re-learning. Every option is documented with a JSDoc typedef, giving IDE hover/autocomplete without hand-authored .d.ts files, and defaults are chosen so a first run is genuinely a single line of config. There’s effectively no required setup, no external service, and no auth to get a working report — the main friction point is understanding the size-metric vocabulary (stat/parsed/gzip/Brotli/Zstandard), which the README documents at length.