Vue CLI Webpack Bundle Analyzer Plugin

4.0.0 · active · verified Sun Apr 19

This package provides a Vue CLI plugin that integrates `webpack-bundle-analyzer` into Vue projects, enabling interactive treemap visualizations of webpack output file sizes. It helps developers understand bundle composition and identify large modules efficiently. The current stable version is 4.0.0, which updated the underlying `webpack-bundle-analyzer` dependency to version 4. The plugin primarily operates via `vue.config.js` `pluginOptions` and offers features like separate reports for modern and legacy builds when using Vue CLI's modern mode. It's an essential tool for build optimization in Vue applications, offering a more integrated experience than configuring `webpack-bundle-analyzer` manually. Its release cadence is tied to updates in `webpack-bundle-analyzer` and Vue CLI itself, ensuring compatibility and access to the latest analyzer features.

Common errors

```
Cannot read properties of undefined (reading 'webpackBundleAnalyzer')
```
cause The `pluginOptions` object or `pluginOptions.webpackBundleAnalyzer` is missing or malformed in `vue.config.js`.

fix Ensure your `vue.config.js` includes `module.exports = { pluginOptions: { webpackBundleAnalyzer: { /* ... */ } } };` and that `webpackBundleAnalyzer` is an object.
```
Analyzer report is not opening in the browser after build.
```
cause The `openAnalyzer` option is set to `false` or the build environment prevents browser launches.

fix Check `pluginOptions.webpackBundleAnalyzer.openAnalyzer` in `vue.config.js`. Set it to `true` if you want it to open automatically (default for production). Alternatively, manually open the generated HTML report file from your output directory.
```
Error: ENOENT: no such file or directory, stat 'legacy-report.html'
```
cause Attempting to access a report file that wasn't generated, possibly due to not building in modern mode or a mismatch in the `reportFilename` configuration.

fix Verify if you built with `vue-cli-service build --modern`. If not, the report won't be prefixed with `legacy-` or `modern-`. Adjust the filename you are looking for, or ensure your build command includes `--modern` if two reports are desired.

Warnings

breaking Version 4.0.0 updated the underlying `webpack-bundle-analyzer` to version 4. This may introduce breaking changes in the available configuration options for `webpackBundleAnalyzer` in `vue.config.js` or alter report behavior.
Fix: Review the `webpack-bundle-analyzer` v4 documentation for changes to plugin options and update your `vue.config.js` configuration accordingly.
breaking In version 2.0.0, the `reportFilename` config option changed how it's handled. It now accepts a full file path rather than just a name. Configurations relying on the older behavior might need adjustment.
Fix: Ensure `reportFilename` in your `pluginOptions.webpackBundleAnalyzer` is a full file path if you intend to specify a custom directory or file structure.
gotcha When building for production, `openAnalyzer` defaults to `true`. This can cause a browser window to open automatically after a successful build, potentially disrupting CI/CD pipelines or automated build processes.
Fix: Explicitly set `openAnalyzer: false` in your `pluginOptions.webpackBundleAnalyzer` within `vue.config.js` to prevent the browser from opening.
gotcha In development mode, `webpack-bundle-analyzer` can only calculate the `stat` size due to its requirement for physical files to compute `parsed` and `gzipped` sizes. The more accurate `parsed` and `gzipped` sizes are only available after a full production build.
Fix: To view `parsed` and `gzipped` sizes, perform a full production build (`npm run build` or `yarn build`).
gotcha When using Vue CLI's `--modern` flag for builds, the plugin generates two distinct reports, prefixed with `legacy-` and `modern-` respectively. If you're expecting a single report, be aware of this dual output.
Fix: When using `--modern`, check for both `legacy-your-report.html` and `modern-your-report.html` (or similar, depending on your `reportFilename` setting) in your output directory.

Install

npm install vue-cli-plugin-webpack-bundle-analyzer npm
yarn add vue-cli-plugin-webpack-bundle-analyzer yarn
pnpm add vue-cli-plugin-webpack-bundle-analyzer pnpm

Imports

Configuration options
wrong:
```
import { WebpackBundleAnalyzerPlugin } from 'vue-cli-plugin-webpack-bundle-analyzer';
```
correct:
```
module.exports = { pluginOptions: { webpackBundleAnalyzer: { /* options */ } } };
```
Users configure this plugin via the `pluginOptions.webpackBundleAnalyzer` object in `vue.config.js`. Direct JavaScript imports from this package are not typically used by developers.
Webpack chain plugin injection
```
config.plugin('webpack-bundle-analyzer').use(BundleAnalyzerPlugin).init(Plugin => new Plugin(options));
```
This is an internal webpack-chain rule automatically injected by the plugin when `vue add` is used. Developers do not write this code directly.
Type definition (implied)
```
/** @type {import('@vue/cli-service').ProjectOptions} */
module.exports = { pluginOptions: { webpackBundleAnalyzer: { /* options */ } } };
```
For TypeScript users, type inference for `pluginOptions` can be enhanced by using JSDoc type annotations or `tsconfig.json` paths for `@vue/cli-service` types, though the plugin itself doesn't export types for direct import.

Quickstart

Installs the plugin and demonstrates basic configuration in `vue.config.js` to disable automatic browser opening and specify output.

vue add webpack-bundle-analyzer

// Then, in vue.config.js, configure options:
// vue.config.js
module.exports = {
  pluginOptions: {
    webpackBundleAnalyzer: {
      openAnalyzer: false, // Prevents opening the analyzer report in the browser automatically
      analyzerMode: 'static', // Generates a static HTML file
      reportFilename: 'bundle-report.html' // Custom report filename
    }
  }
};

// To generate the report, build your project:
// npm run build
// (or yarn build)

view raw JSON →