size-plugin

3.0.0 verified Sat Apr 25 auth: no javascript

A webpack plugin that tracks and displays the gzipped sizes of your assets over time, showing deltas from the previous build. Current stable version is 3.0.0 (2021). Released as needed; maintained by Google Chrome Labs. Key differentiators: simple setup, built-in compression options (gzip, brotli, none), TypeScript types, and automatic file size persistence. Compare to webpack-bundle-analyzer which visualizes composition, or bundlesize which enforces thresholds.

Common errors

error Error: Cannot find module 'size-plugin' ↓

cause SizePlugin is not installed or is in devDependencies but not in node_modules.

fix

Run 'npm install -D size-plugin' or 'yarn add --dev size-plugin'.

error TypeError: SizePlugin is not a constructor ↓

cause Using ES import syntax (import SizePlugin from 'size-plugin') which does not work because the package exports a CommonJS default.

fix

Use 'const SizePlugin = require('size-plugin');'.

error TypeError: Cannot read property 'sizes' of undefined ↓

cause The plugin's beforeRun hook may not run if the webpack config is malformed or the plugin is not instantiated correctly.

fix

Ensure 'new SizePlugin(options)' is added to the plugins array and webpack version is >=4.

error Error: size-plugin: 'compression' option must be one of 'gzip', 'brotli', or 'none' ↓

cause Invalid compression value passed to options.compression.

fix

Set compression to either 'gzip', 'brotli', or 'none'.

Warnings

breaking v3.0.0 drops support for Node.js < 10 and webpack < 4. If you are on older versions, you must upgrade Node.js to >=10 and webpack to >=4. ↓

fix Update Node.js to 10+ and webpack to 4+.

deprecated The 'publish' option was deprecated in v3.0.0. Use 'publishSizes' instead. ↓

fix Rename option to 'publishSizes'.

gotcha The plugin uses a JSON file (default 'size-plugin.json') to persist previous sizes. If you delete this file, all previous size history is lost and deltas will show as 'new'. ↓

fix Keep the file in your project root or configure a custom filename via 'options.filename'.

breaking v2.0.0 introduced a breaking change: the default output format changed and the 'publishSizes' option was added. Existing setups relying on the output format may break. ↓

fix Review the output and adjust any parsing logic.

gotcha If you set 'writeFile: false', the file size history is not saved, so each build will show all assets as 'new' (no delta). ↓

fix Set 'writeFile: true' (default) or provide a custom 'filename'.

Install

npm install size-plugin

yarn add size-plugin

pnpm add size-plugin

Imports

SizePlugin
wrong
```
import SizePlugin from 'size-plugin';
```
correct
```
const SizePlugin = require('size-plugin');
```
CommonJS default export; the package does not ship an ESM build, so named imports or ES import syntax may fail.

SizePlugin

wrong

new SizePlugin([options])

correct

new SizePlugin({ compression: 'gzip' })

Options are passed as an object, not an array.

SizePlugin (TypeScript)

wrong

import { SizePlugin } from 'size-plugin';

correct

import SizePlugin = require('size-plugin'); // or import * as SizePlugin from 'size-plugin'

TypeScript types are provided but only as a namespace export; named import will not find 'SizePlugin'.

Quickstart

Adds the size-plugin to measure and display gzipped sizes of JS assets in webpack output.

// webpack.config.js
const SizePlugin = require('size-plugin');

module.exports = {
  // your webpack config
  plugins: [
    new SizePlugin({
      compression: 'gzip', // default; also 'brotli' or 'none'
      pattern: '*.js',
      exclude: '*.map',
    })
  ]
};