{"id":25433,"library":"esbuild-plugins-node-modules-polyfill","title":"esbuild-plugins-node-modules-polyfill","description":"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.","status":"active","version":"1.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/imranbarbhuiya/esbuild-plugins-node-modules-polyfill","tags":["javascript","esbuild-plugins","esbuild-plugins-node-modules-polyfill","node-modules-polyfill","esbuild","esbuild-plugin","polyfill","node-modules","node-polyfill","typescript"],"install":[{"cmd":"npm install esbuild-plugins-node-modules-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugins-node-modules-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugins-node-modules-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required as the plugin hooks into esbuild's build process","package":"esbuild","optional":false},{"reason":"runtime dependency for actual polyfill implementations of Node.js modules","package":"modern-node-polyfills","optional":false}],"imports":[{"note":"Package ships ESM only. CJS require will fail. Use dynamic import or set type:\"module\" in package.json.","wrong":"const nodeModulesPolyfill = require('esbuild-plugins-node-modules-polyfill')","symbol":"default","correct":"import nodeModulesPolyfill from 'esbuild-plugins-node-modules-polyfill'"},{"note":"Named export is available but default export is the plugin factory. Prefer default import.","wrong":"const { NodeModulesPolyfillPlugin } = require('esbuild-plugins-node-modules-polyfill')","symbol":"NodeModulesPolyfillPlugin","correct":"import { NodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill'"},{"note":"Options is a TypeScript type, not a value. Use `import type` in TypeScript to avoid runtime error.","wrong":"import { Options } from 'esbuild-plugins-node-modules-polyfill'","symbol":"Options","correct":"import type { Options } from 'esbuild-plugins-node-modules-polyfill'"}],"quickstart":{"code":"import * as esbuild from 'esbuild';\nimport nodeModulesPolyfill from 'esbuild-plugins-node-modules-polyfill';\n\nawait esbuild.build({\n  entryPoints: ['app.ts'],\n  outfile: 'out.js',\n  bundle: true,\n  plugins: [nodeModulesPolyfill()],\n  // or with options:\n  // plugins: [nodeModulesPolyfill({ modules: { 'crypto': true, 'fs': false } })],\n});","lang":"typescript","description":"Shows ESM import and usage of the plugin with esbuild build. Includes optional configuration of specific modules."},"warnings":[{"fix":"Explicitly set `modules: { 'moduleName': true }` to allow polyfill, or `false` to disable. Or use `onError` option to customize error handling.","message":"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.","severity":"breaking","affected_versions":">=1.6.0"},{"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;`","message":"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.","severity":"breaking","affected_versions":">=1.8.0"},{"fix":"Upgrade Node.js to version 14.0.0 or later.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use esbuild's `inject` option with paths to polyfill files, e.g., `inject: ['./node_modules/.../process.js']`.","message":"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.","severity":"deprecated","affected_versions":"<1.4.0"},{"fix":"Normalize module names: prefer without `node:` prefix, e.g., `modules: { crypto: true }`.","message":"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.","severity":"gotcha","affected_versions":">=1.6.8"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Switch to `import` or use `const nodeModulesPolyfill = (await import('esbuild-plugins-node-modules-polyfill')).default;` inside an async function.","cause":"Package is ESM-only since v1.8.0. Using `require()` in a CommonJS file fails.","error":"Error: Cannot find module 'esbuild-plugins-node-modules-polyfill'\nRequire stack:\n- /path/to/file.js"},{"fix":"Downgrade esbuild to 0.27.x or wait for a newer release of the plugin that supports esbuild 0.28.","cause":"esbuild 0.28.x is outside the supported peer dependency range (<=0.27.x).","error":"Error: The plugin 'node-modules-polyfill' is not compatible with esbuild version 0.28.x. Supported versions: >=0.14.0 <=0.27.x"},{"fix":"Use default import: `import nodeModulesPolyfill from 'esbuild-plugins-node-modules-polyfill'` and call `nodeModulesPolyfill()`.","cause":"Using named import `{ NodeModulesPolyfillPlugin }` as the default function. The default export is the plugin factory, not the named export.","error":"TypeError: nodeModulesPolyfill is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}