What webpack-bundle-analyzer actually measures, and where it stops

The plugin only sees what your webpack build already wrote

It is a dev dependency rather than a runtime one, and the two documented install paths are the same package under two package managers:

# NPM
npm install --save-dev webpack-bundle-analyzer
# Yarn
yarn add -D webpack-bundle-analyzer

Wiring it into a build means adding the plugin to a webpack configuration, and with no options at all it still runs in `server` mode rather than staying quiet:

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

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

Everything the treemap shows is derived from output that build produced, and none of the documented options tells the plugin to skip work on its own. The way to keep it in the config without a listener is `disabled`, which the table describes as the mode where you can use the plugin to just generate a Webpack Stats JSON file by setting `generateStatsFile` to `true`. The consequence for the reader is that a plugin added to inspect bundles becomes part of what every build does, production and CI runs included, until you set the mode yourself.

The default mode binds 127.0.0.1 on port 8888

`analyzerHost` defaults to `127.0.0.1` and `analyzerPort` defaults to `8888`, so a plain `new BundleAnalyzerPlugin()` opens a loopback listener on a fixed, well known port every time a build runs. The address printed to the console is produced by `analyzerUrl`, a function called with the listen host and the bound address, and its default is `http://${listenHost}:${boundAddress.port}`. Setting `analyzerPort` to `auto` hands port assignment to the operating system, which is the escape hatch when 8888 is already taken on a shared build machine or a developer laptop with another project still listening.

reportFilename is resolved against output.path, not the project root

`reportFilename` defaults to `report.html`, and it accepts either an absolute path or a path relative to a bundle output directory, which the table identifies as `output.path` in the webpack config. The consequence is that one relative filename lands in a different place depending on what your build has set `output.path` to, and a config that sends several bundles to separate directories gives you no single location where the report is guaranteed to appear. In `static` mode this option is the only artifact the plugin writes, so a CI job that collects reports has to know the resolved directory rather than assuming the repository root. In `server` mode the same option is not the artifact you are after at all, since that mode serves the report over HTTP instead of writing it, and in `json` mode you get a single JSON file rather than the HTML page.

defaultSizes names four values, the introduction names three compressors

The report's default size column comes from `defaultSizes`, whose documented values are `stat`, `parsed`, `gzip`, and `brotli`, with `parsed` as the default. Elsewhere in the same README the project says it also shows gzipped, Brotli, or Zstandard sizes, and that it parses minified bundles to get the real size of bundled modules. The defaultSizes row lists no Zstandard value, so check the rest of the options documentation for how Zstandard sizes are selected. It also means the size you see out of the box is the parsed size, not the number of bytes a browser pulls down. If you are chasing a transfer budget, `gzip` or `brotli` are the documented choices, and the default alone will never give you the compressed cost.

Two build pipelines each delete their own output first

The package is produced by two independent steps: `babel src -d lib --copy-files` for the analyzer, then `webpack-cli --node-env=production` for the viewer. Each step starts by removing its own output, `del-cli lib` and `del-cli public`, and the combined clean script runs both. The consequence for anyone working inside the repository is that an interrupted or partial build leaves you without a working entry point, because `main` resolves to `lib/index.js` and the binary to `lib/bin/analyzer.js`, and both live inside directories the build scripts delete on every run. The `watch:analyzer` and `watch:viewer` scripts re-run each half separately, so you can rebuild the analyzer while leaving the viewer untouched. Linting is split the same way, into `eslint --cache .` and `tsc --pretty --noEmit`, with `prettier --cache --ignore-unknown .` as the format check.

The description promises a CLI, the option table only covers the plugin

The package description calls this a webpack plugin and CLI utility that represents bundle content as a convenient interactive zoomable treemap, and the bin entry is `lib/bin/analyzer.js`. The options table is headed for the plugin, and every key it shows, from `analyzerMode` through `defaultSizes`, is described in terms of a webpack config and `output.path`. Nothing in that table explains how to point the CLI at a stats file or a report directory, so a reader who wants to inspect a build without recompiling it has to find that out somewhere else. The repository is at least readable as a map, with `src/`, `client/`, `bin/`, and `test/` at the top level alongside `CHANGELOG.md`, `CONTRIBUTING.md`, `.changeset/`, `jest.config.js`, and `tsconfig.json`.

Maintained through v5.4.0, tested under a legacy OpenSSL flag

Version 5.4.1 in package.json was released on 2026-11-02, following 5.4.0 on 2026-09-17 and 5.3.3 on 2026-09-10, and the repository received its most recent push on 2026-11-02. That cadence is a fair reason to treat the project as actively maintained, though the recent history is a run of patch and minor releases rather than a rewrite. The test script sets NODE_OPTIONS to the openssl-legacy-provider flag before invoking Jest, which is worth knowing before you try to reproduce the suite on a current Node release. The author field names Yury Grunin, and the license is MIT.

Editorial conclusion

Reach for it when the bundle is yours and webpack wrote it: the plugin form gives you a documented options table and a default that needs an explicit mode from you, while the CLI form ships as a binary at lib/bin/analyzer.js. Walk away if your build is not webpack, or if a fixed default port in a shared build environment is a problem you would rather not own. Before you commit, check which analyzerMode your CI runs leave in place, confirm reportFilename against your own output.path, and check how the Zstandard size advertised in the introduction is selected, since defaultSizes lists only stat, parsed, gzip and brotli.

Frequently asked questions

Official sources

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