esbuild-plugins-node-modules-polyfill

1.8.1 verified Fri May 01 auth: no javascript

An esbuild plugin that polyfills Node.js built-in modules (e.g., buffer, crypto, path, fs, stream, events) and globals for browser environments. Current stable version is 1.8.1, maintained actively with releases roughly monthly. It uses the modern-node-polyfills npm package internally and supports esbuild peer dependencies between 0.14.x and 0.27.x. Key differentiators: it is the most comprehensive and actively maintained esbuild polyfill plugin, supports custom error formatting, empty fallbacks, and the `browser` field in package.json. It also injects Node.js globals like `process` and `Buffer` via esbuild's `inject` functionality.

Common errors

error Error: Cannot find module 'esbuild-plugins-node-modules-polyfill' Require stack: - /path/to/file.js ↓

cause Package is ESM-only since v1.8.0. Using `require()` in a CommonJS file fails.

fix

Switch to import or use const nodeModulesPolyfill = (await import('esbuild-plugins-node-modules-polyfill')).default; inside an async function.

error Error: The plugin 'node-modules-polyfill' is not compatible with esbuild version 0.28.x. Supported versions: >=0.14.0 <=0.27.x ↓

cause esbuild 0.28.x is outside the supported peer dependency range (<=0.27.x).

fix

Downgrade esbuild to 0.27.x or wait for a newer release of the plugin that supports esbuild 0.28.

error TypeError: nodeModulesPolyfill is not a function ↓

cause Using named import `{ NodeModulesPolyfillPlugin }` as the default function. The default export is the plugin factory, not the named export.

fix

Use default import: import nodeModulesPolyfill from 'esbuild-plugins-node-modules-polyfill' and call nodeModulesPolyfill().

Warnings

breaking Since v1.6.0, the plugin now supports custom error formatting. The default behavior changed: unhandled modules now throw an error instead of silently falling back to empty objects. If you relied on silent fail, use the `modules` option to map them to empty or custom polyfills. ↓

fix Explicitly set `modules: { 'moduleName': true }` to allow polyfill, or `false` to disable. Or use `onError` option to customize error handling.

breaking The plugin is ESM-only as of v1.8.0. `require()` will throw a runtime error. Must use `import` or dynamic `import()` (if inside a CJS file) or use a bundler that understands ESM. ↓

fix Change `require()` to `import`. If your project is CJS, you can use dynamic import: `const nodeModulesPolyfill = (await import('esbuild-plugins-node-modules-polyfill')).default;`

breaking Node.js version <14.0.0 is not supported. The `engines` field requires >=14. Running on older Node may cause unexpected errors or missing features. ↓

fix Upgrade Node.js to version 14.0.0 or later.

deprecated The `inject` global polyfill for `process` and `Buffer` is now handled via esbuild's `inject` feature. In versions prior to 1.4.0, the plugin automatically injected globals. Starting from 1.4.0, you must explicitly enable injection via esbuild's `inject` option or rely on polyfill modules. ↓

fix Use esbuild's `inject` option with paths to polyfill files, e.g., `inject: ['./node_modules/.../process.js']`.

gotcha The `modules` option accepts both module names with and without the `node:` prefix. However, if you mix prefixes, duplicate entries will cause warnings. Use consistent naming (either all prefixed or all unprefixed) to avoid unexpected behavior. ↓

fix Normalize module names: prefer without `node:` prefix, e.g., `modules: { crypto: true }`.

Install

npm install esbuild-plugins-node-modules-polyfill

yarn add esbuild-plugins-node-modules-polyfill

pnpm add esbuild-plugins-node-modules-polyfill

Imports

default

wrong

const nodeModulesPolyfill = require('esbuild-plugins-node-modules-polyfill')

correct

import nodeModulesPolyfill from 'esbuild-plugins-node-modules-polyfill'

Package ships ESM only. CJS require will fail. Use dynamic import or set type:"module" in package.json.

NodeModulesPolyfillPlugin

wrong

const { NodeModulesPolyfillPlugin } = require('esbuild-plugins-node-modules-polyfill')

correct

import { NodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill'

Named export is available but default export is the plugin factory. Prefer default import.

Options

wrong

import { Options } from 'esbuild-plugins-node-modules-polyfill'

correct

import type { Options } from 'esbuild-plugins-node-modules-polyfill'

Options is a TypeScript type, not a value. Use `import type` in TypeScript to avoid runtime error.

Quickstart

Shows ESM import and usage of the plugin with esbuild build. Includes optional configuration of specific modules.

import * as esbuild from 'esbuild';
import nodeModulesPolyfill from 'esbuild-plugins-node-modules-polyfill';

await esbuild.build({
  entryPoints: ['app.ts'],
  outfile: 'out.js',
  bundle: true,
  plugins: [nodeModulesPolyfill()],
  // or with options:
  // plugins: [nodeModulesPolyfill({ modules: { 'crypto': true, 'fs': false } })],
});