webpack-bundle-tracker

3.2.3 verified Sat Apr 25 auth: no javascript

Webpack plugin that outputs compilation statistics (status, chunks, assets) to a JSON file, primarily designed to integrate with django-webpack-loader for server-side rendering of webpack bundles in Django projects. Current stable version: 3.2.3 (released January 2025). Releases are synced with django-webpack-loader. Key differentiators: supports integrity hashes, relative paths, log timing, and compiles down to CJS for Node.js compatibility. Requires Node >=20.0.0. Provides TypeScript type definitions.

Common errors

error Cannot find module 'webpack-bundle-tracker' ↓

cause Package not installed or dev dependency missing.

fix

npm install --save-dev webpack-bundle-tracker

error BundleTracker is not a constructor ↓

cause Importing as named export instead of default.

fix

Use: const BundleTracker = require('webpack-bundle-tracker');

error TypeError: Cannot read properties of undefined (reading 'compilation') ↓

cause Plugin instantiated outside webpack plugin array or webpack version incompatible.

fix

Ensure BundleTracker is in plugins array and webpack >=5 for v3.x.

error The 'path' argument must be of type string. Received undefined ↓

cause Missing or incorrect 'path' option in plugin constructor.

fix

Provide a valid path string: path: __dirname or path.resolve('./stats')

Warnings

breaking Node.js >=17 with OpenSSL v3 breaks Webpack@4; set NODE_OPTIONS=--openssl-legacy-provider. ↓

fix Set environment variable NODE_OPTIONS=--openssl-legacy-provider before running webpack.

breaking Migrating from v1 to v2: 'path' option now used with 'filename' to generate output path; subdirectories in 'filename' no longer allowed. ↓

fix Move subdirectory segments from 'filename' to 'path' option.

deprecated lodash dependency removed in v3.2.1; no migration needed but ensure no reliance on internal lodash polyfills. ↓

fix No action required; upgrade to v3.2.1+.

breaking Version 3.0.0 requires webpack 5 (publicPath: auto support removed for webpack 4). ↓

fix Upgrade to webpack 5 or use v2.x.

gotcha The stats JSON is emitted on the 'emit' hook; ensure plugins order if using other emit plugins. ↓

fix If other plugins depend on the stats file, adjust plugin order or use compiler hooks.

Install

npm install webpack-bundle-tracker

yarn add webpack-bundle-tracker

pnpm add webpack-bundle-tracker

Imports

BundleTracker

wrong

import BundleTracker from 'webpack-bundle-tracker';

correct

const BundleTracker = require('webpack-bundle-tracker');

Package is CJS-only; no ESM export. Use require().

BundleTracker

wrong

const { BundleTracker } = require('webpack-bundle-tracker');

correct

const Plugin = require('webpack-bundle-tracker');

Export is default, not named. Destructuring will yield undefined.

BundleTrackerOptions
```
import type { BundleTrackerOptions } from 'webpack-bundle-tracker';
```
TypeScript users can import the type for options (path, filename, etc.).

Quickstart

Shows minimal webpack config using BundleTracker plugin to output stats JSON file.

const path = require('path');
const BundleTracker = require('webpack-bundle-tracker');

module.exports = {
  context: __dirname,
  entry: './src/index.js',
  output: {
    path: path.resolve('./dist'),
    filename: '[name]-[contenthash].js',
  },
  plugins: [
    new BundleTracker({
      path: __dirname,
      filename: 'webpack-stats.json',
    }),
  ],
};