bundle-stats

library4.22.1jsnpmunverified

bundle-stats is an in-depth bundle analyzer for webpack, Rspack, Vite, Rollup, and Rolldown that provides detailed reports on bundle size, assets, modules, and packages. It supports comparing multiple builds side-by-side to identify changes, duplicate packages, and new dependencies. Current stable version is 4.22.1, released in April 2025, with active maintenance and frequent updates. Key differentiators include its cross-bundler support via rollup-plugin-webpack-stats, insights like cache invalidation and initial JS/CSS metrics, and a CLI for CI integration. Ships TypeScript types. Requires Node >= 14.

devops

npm install bundle-stats

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUNDLE-STATS

bundle-stats

devopsjavascriptv4.22.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BundleStatsWebpackPlugin

✓ import { BundleStatsWebpackPlugin } from 'bundle-stats/webpack'

✗ import BundleStatsWebpackPlugin from 'bundle-stats'

Webpack plugin is exported from 'bundle-stats/webpack' subpath. Default import from 'bundle-stats' is the main CLI function, not the plugin.

bundleStats

✓ import bundleStats from 'bundle-stats'

✗ import { bundleStats } from 'bundle-stats'

The main entry exports a default function for CLI usage. Named export does not exist.

rollupPluginBundleStats

✓ import { rollupPluginBundleStats } from 'bundle-stats/rollup'

✗ import rollupPluginBundleStats from 'bundle-stats'

Rollup/Vite plugin is exported from 'bundle-stats/rollup' subpath. Not available from the main entry.

Shows how to generate webpack stats JSON, run CLI analysis for single/multiple builds, and use the package programmatically in an ESM TypeScript context.

// Generate webpack stats JSON npx webpack --profile --json > stats.json // Analyze with bundle-stats CLI npx bundle-stats stats.json --output-dir ./bundle-stats // For multiple builds comparison: npx bundle-stats stats1.json stats2.json --output-dir ./bundle-stats // Programmatic usage (ESM): import bundleStats from 'bundle-stats'; const result = await bundleStats({ stats: [{ path: 'stats.json' }], outputDir: './bundle-stats', baseline: false, }); console.log(result);

bundle-stats --version

Debug

Known issues

gotchaThe main export is a default function, not a named export. Using `import bundleStats from 'bundle-stats'` is correct, but `import { bundleStats } from 'bundle-stats'` will fail.

fix

Use default import: `import bundleStats from 'bundle-stats'`.

affects: >=4.0.0

gotchaWebpack plugin must be imported from 'bundle-stats/webpack', not from the main package. Using `import { BundleStatsWebpackPlugin } from 'bundle-stats'` will give undefined.

fix

Import from 'bundle-stats/webpack'.

affects: >=4.0.0

gotchaRollup/Vite plugin is imported from 'bundle-stats/rollup', not from the main package or 'bundle-stats/vite'. There is no separate 'vite' subpath export.

fix

Use `import { rollupPluginBundleStats } from 'bundle-stats/rollup'`.

affects: >=4.0.0

breakingDropped support for Node < 14 as of v4. The engines field specifies node >= 14.0.

fix

Upgrade Node to >= 14.0.

affects: >=4.0.0

deprecatedThe `compare` mode via CLI `--compare` flag is deprecated in favor of passing multiple stats files as arguments.

fix

Pass multiple files: `npx bundle-stats stats1.json stats2.json`.

affects: >=4.0.0

Errors

Common errors & fixes

Error: Cannot find module 'bundle-stats/webpack'

Package 'bundle-stats' is not installed or import path is wrong (e.g., using 'bundle-stats' without '/webpack' subpath).

fix

Run `npm install bundle-stats` and use `import { BundleStatsWebpackPlugin } from 'bundle-stats/webpack'`.

TypeError: bundleStats is not a function

Using named import `{ bundleStats }` instead of default import.

fix

Use `import bundleStats from 'bundle-stats'`.

Error: Stats file stats.json does not exist or is not a valid JSON file

The CLI argument points to a missing or malformed stats file (must be valid webpack stats JSON).

fix

Ensure stats file is generated with `npx webpack --profile --json > stats.json` and exists at the given path.

Upgrade

Version history

4.22.1latest on npm

Audit

Dependencies

webpackoptionalRequired when used as a webpack plugin (BundleStatsWebpackPlugin) or for analyzing webpack stats.

rollupoptionalRequired when used with Rollup or Vite via rollup-plugin-webpack-stats.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/relative-ci/bundle-stats ↗

packagehttps://www.npmjs.com/package/bundle-stats ↗

homepagehttps://www.bundlestats.com ↗