Skip to content
Get packs

Guide · Open source

How to use webpack-bundle-analyzer: install and read the treemap

Updated · written with AI from the project's own documentation and checked against our catalogue data

webpack-bundle-analyzer is an open-source (MIT) Webpack plugin and CLI utility that draws your bundle's contents as an interactive, zoomable treemap. Each box's size reflects how much space a module takes up. This guide shows you how to install it, add it to a webpack config, and read the report to find what is making your bundle large. It is written for developers who already use webpack.

Webpack Bundle Analyzerwebpack/webpack-bundle-analyzer · ★ 12.7k · MIT

Quick start

  1. 1Install the package. Run npm install --save-dev webpack-bundle-analyzer, or yarn add -D webpack-bundle-analyzer, in your project.
  2. 2Import the plugin. Add const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer") to your webpack config file.
  3. 3Add it to plugins. Push new BundleAnalyzerPlugin() into the plugins array of your webpack configuration.
  4. 4Run your build. Build your project with webpack so the analyzer can read the output bundles.
  5. 5Open the treemap. In the default server mode, the report is served over HTTP and opens in your browser unless openAnalyzer is false.
  6. 6Zoom in and inspect. Click into large boxes to see the modules inside and identify ones that are bigger than expected.

What you need before you install webpack-bundle-analyzer

The tool is built around webpack output, so you need a project that builds with webpack. The source lists Node.js and webpack as prerequisites.

It is installed as a development dependency with your package manager of choice.

  • Node.js
  • webpack (your project must already use it)
  • npm or Yarn

Install webpack-bundle-analyzer with npm or Yarn

Run the command that matches your package manager from your project folder. The --save-dev flag (or -D with Yarn) adds the package as a development dependency.

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

Add the plugin to your webpack config

Import BundleAnalyzerPlugin from the package and add a new instance to the plugins array of your webpack configuration. With no options, the plugin creates an interactive treemap of the contents of all your bundles.

By default the plugin runs in server mode, which starts an HTTP server to show the report. You can change that with options such as analyzerMode.

const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer"); module.exports = { plugins: [new BundleAnalyzerPlugin()], };

Read the treemap to find large modules

Each box in the treemap is a module, and its size shows how much space it takes up in the bundle. Zoom in to see the modules inside a box. The source describes the tool as a way to realise what is really inside your bundle, find which modules make up most of its size, and find modules that got there by mistake.

The tool parses minified bundles to estimate the real size of bundled modules. It can also show gzipped, Brotli, or Zstandard sizes. The defaultSizes option sets which size is shown first, with the default being parsed.

  • Look for large boxes that you did not expect to see.
  • Check whether an unexpected library has been bundled.
  • Compare module sizes before and after a change.

Choose an output mode and common options

The analyzerMode option controls how the report is delivered. server starts an HTTP server (the default), static writes a single HTML file, json writes a single JSON file, and disabled skips the report so you can use the plugin only to generate a Webpack Stats JSON file by setting generateStatsFile to true.

In static mode, reportFilename sets the output path of the HTML file, relative to your bundle output directory by default. analyzerHost and analyzerPort control the server address, with port 8888 as the default. Setting openAnalyzer to false stops the report from opening automatically in your browser.

  • analyzerMode: server (default), static, json, disabled
  • analyzerHost: default 127.0.0.1
  • analyzerPort: default 8888, or auto to let the OS pick a free port
  • reportFilename: default report.html
  • openAnalyzer: default true
  • compressionAlgorithm: gzip (default), brotli, or zstd
new BundleAnalyzerPlugin({ analyzerMode: "static", openAnalyzer: false, })

What people use it for

  • Finding an unexpected library that was pulled into a bundle by mistake.
  • Seeing which modules make up most of a slow-loading webpack bundle.
  • Comparing module sizes in a visual, clickable report.
  • Generating a static HTML report to share with a team.
  • Producing a JSON report or Webpack Stats file for further processing.

Frequently asked questions

Is webpack-bundle-analyzer free?

Yes. The project is released under the MIT licence, and the source lists MIT as its licence.

What do I need to run webpack-bundle-analyzer?

The source lists Node.js and webpack as prerequisites. The tool is built around webpack output, so it is not meant for projects that do not use webpack.

How do I install webpack-bundle-analyzer?

Run npm install --save-dev webpack-bundle-analyzer with npm, or yarn add -D webpack-bundle-analyzer with Yarn.

Can it show gzip or Brotli sizes?

Yes. The tool can report gzip, Brotli, or Zstandard sizes, and compressionAlgorithm sets which one is used to calculate compressed sizes.

Can I generate a report without opening a server?

Yes. Set analyzerMode to static to write a single HTML file, or to json to write a JSON file. Setting openAnalyzer to false also stops the report from opening automatically.

What are alternatives to webpack-bundle-analyzer?

The source lists source-map-explorer, webpack-visualizer, statoscope, and size-limit as comparable projects. This guide does not compare their features, so check each project's own documentation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

webpack-bundle-analyzer suits frontend developers who use webpack and want a visual, clickable view of what is inside their bundles. It is less suited to projects that do not use webpack, or to anyone who only needs a single size number, since it requires editing a webpack config or running a build.

Install options & downloads