webpack-bundle-analyzer: reading your bundle as a zoomable treemap

What webpack-bundle-analyzer is for, and who actually needs it

The README frames the module around four jobs: realizing what is really inside your bundle, finding which modules make up most of its size, finding modules that got there by mistake, and optimizing it. That list is honest about the scope. This is not a build-time optimizer. It does not remove a dependency or rewrite an import. It answers a question you have already decided to ask: what is in here, and how big is each part.

The people who get value from it are working on a webpack build that has grown past the point where the config file tells the whole story. Transitive dependencies pulled in by a helper library, a polyfill duplicated across chunks, a package that ships a full locale set when you needed one language. None of that is visible in package.json. It is visible in the stats output, and the treemap is a way of reading that output quickly.

It is the wrong tool for the person who has not yet decided whether size is a problem. There is no budget, no threshold, no automatic regression check in the plugin itself. It renders. You interpret.

How the treemap gets built: plugin, stats, client

The plugin hooks into the webpack compilation and receives the stats object. Depending on analyzerMode, it either starts an HTTP server, writes a single HTML file, writes a JSON file, or does nothing but let you generate the stats file through generateStatsFile. The default is server.

The report itself is a treemap: nested rectangles where area corresponds to size, and the client in the client directory handles the zooming. The README notes that it supports minified bundles and parses them to get the real size of bundled modules. That parsing step is the reason the tool is useful on production builds rather than only on development output.

Size is not a single number. The defaultSizes option selects which one the report shows first, and the accepted values are stat, parsed, gzip, and brotli. The README also states that the report shows gzipped, Brotli, or Zstandard sizes. Having four representations of the same module is the point: a 40 KB source file that compresses to 9 KB is a different problem from a 40 KB file that compresses to 38 KB, and a single number would hide that.

Installing it and generating a first report

Install it as a development dependency. The README gives both package managers:

npm install --save-dev webpack-bundle-analyzer

Then add the plugin to your webpack configuration. The README's minimal example requires the named export BundleAnalyzerPlugin and places an instance in the plugins array:

const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer");

module.exports = {
  plugins: [new BundleAnalyzerPlugin()],
};

Run your normal build. With the default analyzerMode of server, the plugin starts an HTTP server on analyzerHost 127.0.0.1 and analyzerPort 8888, and prints a URL to the console. Open it and you get the interactive treemap of every bundle in the compilation. Click a rectangle to zoom in; the breadcrumb path shows where you are.

For a build you do not want to babysit, switch to static mode. The reportFilename option defaults to report.html and may be an absolute path or a path relative to the bundle output directory, which is output.path in the webpack config. Setting analyzerMode to json produces a JSON report instead, and analyzerMode disabled combined with generateStatsFile true gives you only the raw webpack stats file. If 8888 is taken, analyzerPort accepts the string auto, and the operating system assigns an arbitrary unused port.

Where it stops being the right tool

The plugin is tied to webpack. It consumes webpack stats. If your build runs through a different bundler, there is nothing here for you unless that tool can emit a webpack-compatible stats file, and the README does not describe such a path. The related searches around Vite point at exactly this gap, and the repository does not fill it.

Server mode is the default and it is the wrong default for automated environments. It starts a long-lived HTTP server bound to 127.0.0.1:8888 and waits. On a CI machine that means a job that does not exit, or an exposed port you did not intend. You have to remember to set analyzerMode to static, json, or disabled for those runs. The README documents the modes but does not warn about this.

The minified-bundle parsing is described as a capability, not as a guarantee. The README does not state which minifier output shapes it handles, or what happens when a bundle has been transformed in a way the parser does not recognize. Treat the parsed size of a heavily post-processed bundle as an estimate to cross-check, not as a measurement to quote.

Finally, the plugin tells you the size of what you shipped. It does not tell you whether that size matters for your users. A module that loads lazily on a rarely visited route is a different cost from one in the entry chunk, and the treemap shows the module, not the loading strategy.

How it differs from source-map-explorer and from webpack's own stats

The closest alternative in spirit is source-map-explorer. The difference is the input. source-map-explorer reads your build output together with its source maps and attributes bytes to original source files. webpack-bundle-analyzer reads webpack's stats and parses the emitted bundles, and the README states it works on minified bundles without requiring source maps to be published or retained. If your production build strips source maps, that distinction decides which tool you can run at all. If you want attribution back to original source paths, source-map-explorer's approach is the one built for it.

The other alternative is not a tool at all: webpack's own stats output. You can set generateStatsFile to true through this plugin and read the JSON yourself, or write your own script against it. That gives you complete control over what you compute and how you alert on it, at the cost of building the entire presentation layer. The plugin's value is the client in the client directory and the treemap rendering, not the stats collection, which webpack already does.

Maintenance, releases, and what the MIT licence covers

The repository is not archived, and the last push was on 2026-09-17. Releases have been frequent through 2026: v5.3.2 on 2026-08-23, v5.3.3 on 2026-09-10, and v5.4.0 on 2026-09-17. The package.json shows version 5.4.0 and a publish script that runs lint, build, and test before npm publish, so a release implies those steps passed in the maintainer's environment.

Upgrade cost is low if you use the plugin as documented. The public surface is the BundleAnalyzerPlugin constructor and its options object, plus the CLI entry at bin/analyzer.js. Major versions are where you would expect breaking changes; the README does not document a migration path from v4 to v5, so read CHANGELOG.md before jumping a major. The repository uses a .changeset directory, which means individual changes are recorded as they land rather than reconstructed at release time.

The licence is MIT. That permits commercial and private use, modification, and redistribution provided the copyright notice and permission notice are included. It offers no patent grant and no warranty, and it does not require you to publish your modifications. This is a factual description of the licence text, not legal advice; if your organisation has rules about which licences are acceptable in a build toolchain, route it through whoever owns that policy.

Editorial conclusion

Adopt it if you ship a webpack build and need to see which modules occupy the most space, especially when you must inspect minified output. Skip it if your bundler is not webpack and you have no webpack stats file to feed it, and skip the server mode on CI where a long-lived HTTP server on 127.0.0.1:8888 is the wrong shape. Before rolling it out, verify two things: that your webpack version produces stats the plugin can parse, and that you have settled on static or json mode for automated runs rather than the default server mode.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. webpack/webpack-bundle-analyzer on GitHub