Registry / http-networking / esbuild-plugins-node-modules-polyfill

esbuild-plugins-node-modules-polyfill

library1.8.1jsnpmunverified

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.

http-networking serialization

npm install esbuild-plugins-node-modules-polyfill

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGINS-NO

esbuild-plugins-node-modules-polyfill

http-networkingjavascriptv1.8.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

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

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

NodeModulesPolyfillPlugin

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

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

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

Options

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

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

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

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 } })], });

Debug

Known issues

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

affects: >=1.6.0

breakingThe 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;`

affects: >=1.8.0

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

affects: >=1.0.0

deprecatedThe `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']`.

affects: <1.4.0

gotchaThe `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 }`.

affects: >=1.6.8

Errors

Common errors & fixes

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

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: The plugin 'node-modules-polyfill' is not compatible with esbuild version 0.28.x. Supported versions: >=0.14.0 <=0.27.x

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.

TypeError: nodeModulesPolyfill is not a function

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()`.

Upgrade

Version history

1.8.1latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency required as the plugin hooks into esbuild's build process

modern-node-polyfillsrequiredruntime dependency for actual polyfill implementations of Node.js modules

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/imranbarbhuiya/esbuild-plugins-node-modules-polyfill ↗

packagehttps://www.npmjs.com/package/esbuild-plugins-node-modules-polyfill ↗