Heap Sampling Webpack Plugin

1.2.2 verified Sat Apr 25 auth: no javascript

A Webpack plugin that adds heap sampling profiling to builds using Node.js Inspector HeapProfiler. It generates .heapprofile files openable in Chromium DevTools Memory tab. Version 1.2.2 is stable with no recent updates. Unlike CPU profiling (e.g., webpack.debug.ProfilingPlugin), this focuses on memory allocation, suitable for production builds to diagnose memory consumption in build machines. Configuration is minimal via Webpack plugin array.

Common errors

error Error: Inspector is not available ↓

cause Node.js runtime does not support Inspector (e.g., in some bundled environments).

fix

Ensure you are using a standard Node.js runtime (not a stripped-down build) and that the process has inspector permissions.

error TypeError: HeapSamplingPlugin is not a constructor ↓

cause Incorrect import style (used ES module import on CommonJS module).

fix

Use require('heap-sampling-webpack-plugin') instead of import.

error heapprofile file empty or not generated ↓

cause Plugin runs after compilation but may not have permission to write to outputPath.

fix

Ensure outputPath directory exists and is writable. Use absolute path or ensure relative path is correct for Webpack context.

Warnings

gotcha Plugin uses Node.js Inspector protocol, which may not be available in all environments (e.g., restricted Docker containers). ↓

fix Ensure Node.js process has inspector access (--inspect flag not required, but runtime must support Inspector).

gotcha Output file is overwritten on each build without warning. ↓

fix Use a unique filename per build (e.g., include timestamp in outputPath).

deprecated The plugin has not been updated in several years; may not work with Webpack 5+ due to internal API changes. ↓

fix Test with your Webpack version; consider alternatives like webpack-bundle-analyzer for memory analysis.

gotcha Heap sampling increases build time and memory usage significantly. ↓

fix Use only for diagnostic builds, not in CI pipeline for every commit.

Install

npm install heap-sampling-webpack-plugin

yarn add heap-sampling-webpack-plugin

pnpm add heap-sampling-webpack-plugin

Imports

HeapSamplingPlugin

wrong

import HeapSamplingPlugin from 'heap-sampling-webpack-plugin';

correct

const HeapSamplingPlugin = require('heap-sampling-webpack-plugin');

Plugin is CommonJS only; no ES module wrapper provided.

new HeapSamplingPlugin()

wrong

new HeapSamplingPlugin('/path/to/file.heapprofile')

correct

new HeapSamplingPlugin({ outputPath: '/path/to/file.heapprofile' })

Options are passed as an object, not a string. The only option is outputPath.

HeapSamplingPlugin as type (TypeScript)

wrong

import { HeapSamplingPlugin } from 'heap-sampling-webpack-plugin';

correct

declare module 'heap-sampling-webpack-plugin' { const HeapSamplingPlugin: any; export = HeapSamplingPlugin; }

No TypeScript types included; use any or declare module manually.

Quickstart

Shows basic Webpack configuration with HeapSamplingPlugin enabling heap profiling output to a file.

const HeapSamplingPlugin = require('heap-sampling-webpack-plugin');

module.exports = {
  plugins: [
    new HeapSamplingPlugin({
      outputPath: '/tmp/build.heapprofile'
    })
  ]
};