node-polyfill-webpack-plugin

4.1.0 verified Sat Apr 25 auth: no javascript

Webpack 5 removed automatic Node.js core module polyfills, breaking many packages that rely on them. This plugin restores those polyfills (Buffer, process, crypto, path, etc.) by injecting lightweight browser-compatible implementations. Current stable version is 4.1.0, released in 2024. Requires Node >=14 and Webpack >=5. Compared to manual fallbacks or patch-package, it provides a single plugin configuration. v4 dropped several modules from defaults (console, domain, process, internal streams) and renamed includeAliases to additionalAliases. Ships TypeScript definitions.

Common errors

error Module not found: Error: Can't resolve 'crypto' in '/path/to/project/src' ↓

cause Webpack 5 no longer polyfills Node core modules; plugin not added or not configured correctly.

fix

Add NodePolyfillPlugin to webpack plugins.

error Class constructor NodePolyfillPlugin cannot be invoked without 'new' ↓

cause CommonJS require returns the class itself, not a factory function.

fix

Use new NodePolyfillPlugin() instead of NodePolyfillPlugin()

error TypeError: NodePolyfillPlugin is not a constructor ↓

cause Using ES module import syntax with a CJS-only package without proper configuration.

fix

Use require() or configure bundler to handle CJS interop.

Warnings

breaking console, domain, process, and internal stream modules are no longer polyfilled by default in v4. ↓

fix Use 'additionalAliases' option to explicitly include them.

deprecated The 'includeAliases' option has been renamed to 'additionalAliases' in v4. ↓

fix Rename 'includeAliases' to 'additionalAliases' in your config.

breaking Node.js 12 support dropped; requires Node >=14. ↓

fix Upgrade Node.js to version 14 or higher.

gotcha fs module resolves to an empty object (not polyfilled) because it cannot be implemented in the browser. ↓

fix Avoid using 'fs' in browser code or provide a custom mock via webpack aliases.

gotcha The plugin only works with Webpack 5; Webpack 4 already had Node polyfills built in. ↓

fix If using Webpack 4, you don't need this plugin.

gotcha Using 'onlyAliases' overrides default polyfills; you must include everything you need manually. ↓

fix List all required aliases in 'onlyAliases' array, including defaults if still needed.

Install

npm install node-polyfill-webpack-plugin

yarn add node-polyfill-webpack-plugin

pnpm add node-polyfill-webpack-plugin

Imports

NodePolyfillPlugin

wrong

import NodePolyfillPlugin from 'node-polyfill-webpack-plugin';

correct

const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');

Package is CJS-only, does not export ESM. Use require() in Node.

NodePolyfillPlugin
wrong
```
new NodePolyfillPlugin.default()
```
correct
```
new NodePolyfillPlugin()
```
The plugin is a constructor, not an object with a default property.

NodePolyfillPlugin

wrong

import { NodePolyfillPlugin } from 'node-polyfill-webpack-plugin';

correct

const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');

Named import from CJS package is not supported in native ESM.

Quickstart

Basic webpack config that adds Node.js core module polyfills to a browser bundle.

// webpack.config.js
const path = require('path');
const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
  },
  plugins: [
    new NodePolyfillPlugin()
  ]
};