bundle-stats

4.22.1 verified Sat Apr 25 auth: no javascript

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.

Common errors

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

cause 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'.

error TypeError: bundleStats is not a function ↓

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

fix

Use import bundleStats from 'bundle-stats'.

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

cause 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.

Warnings

gotcha The 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'`.

gotcha Webpack 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'.

gotcha Rollup/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'`.

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

fix Upgrade Node to >= 14.0.

deprecated The `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`.

Install

npm install bundle-stats

yarn add bundle-stats

pnpm add bundle-stats

Imports

BundleStatsWebpackPlugin
wrong
```
import BundleStatsWebpackPlugin from 'bundle-stats'
```
correct
```
import { BundleStatsWebpackPlugin } from 'bundle-stats/webpack'
```
Webpack plugin is exported from 'bundle-stats/webpack' subpath. Default import from 'bundle-stats' is the main CLI function, not the plugin.
bundleStats
wrong
```
import { bundleStats } from 'bundle-stats'
```
correct
```
import bundleStats from 'bundle-stats'
```
The main entry exports a default function for CLI usage. Named export does not exist.
rollupPluginBundleStats
wrong
```
import rollupPluginBundleStats from 'bundle-stats'
```
correct
```
import { rollupPluginBundleStats } from 'bundle-stats/rollup'
```
Rollup/Vite plugin is exported from 'bundle-stats/rollup' subpath. Not available from the main entry.

Quickstart

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);