esbuild-plugin-polyfill-node

0.3.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin for polyfilling Node.js built-in modules and globals in browser, edge, and Deno environments. Version 0.3.0 is the latest stable release, actively maintained by cyco130. It leverages @jspm/core for polyfills and offers fine-grained control over individual polyfills via options. The plugin includes two variants: polyfillNode for general edge use and polyfillNodeForDeno which uses Deno's std/node library. Key differentiators include support for both Deno and Deno Deploy, configurable globals (Buffer, process, __dirname, __filename), and the ability to disable or replace specific polyfills with empty stubs or npm packages.

Common errors

error Error: [esbuild] No matching polyfill for module 'crypto' ↓

cause The 'crypto' polyfill is not enabled by default.

fix

Add { polyfills: { crypto: true } } to plugin options.

error TypeError: Cannot read properties of undefined (reading 'NODE_ENV') ↓

cause The 'process' global is not polyfilled by default when globals.process is false, but code expects process.env.

fix

Either set globals.process: true or use esbuild's define option: --define:process.env.NODE_ENV='production'

error Error: Cannot find module 'buffer' ↓

cause The buffer polyfill might be disabled but code requires Buffer.

fix

Enable buffer polyfill: set globals.buffer: true or import 'buffer' polyfill explicitly.

Warnings

gotcha The 'crypto' and 'fs' polyfills are disabled by default; they must be explicitly enabled in the polyfills option to be included. ↓

fix Set polyfills: { crypto: true, fs: true } in plugin options.

gotcha Enabling the 'Buffer' global (globals.buffer: true) will inject the buffer-es6 polyfill which is large; code like 'if (typeof Buffer !== "undefined")' will cause it to be included unnecessarily. ↓

fix Set globals.buffer: false unless your code explicitly uses Buffer.

gotcha The polyfillNodeForDeno plugin uses Deno's std/node library, which was removed from Deno core in v0.178.0. This plugin is only useful for Deno Deploy, not newer Deno versions. ↓

fix Use polyfillNodeForDeno only for Deno Deploy targets; for Deno >=0.178.0 use native node: imports.

Install

npm install esbuild-plugin-polyfill-node

yarn add esbuild-plugin-polyfill-node

pnpm add esbuild-plugin-polyfill-node

Imports

polyfillNode

wrong

const polyfillNode = require('esbuild-plugin-polyfill-node')

correct

import { polyfillNode } from 'esbuild-plugin-polyfill-node'

Default export is not supported; use named import.

polyfillNodeForDeno

wrong

import { polyfillNodeForDeno } from 'esbuild-plugin-polyfill-node/deno'

correct

import { polyfillNodeForDeno } from 'esbuild-plugin-polyfill-node'

Both plugins are exported from the main package, no separate path needed.

polyfillNode (CommonJS)

wrong

const polyfillNode = require('esbuild-plugin-polyfill-node').default

correct

const { polyfillNode } = require('esbuild-plugin-polyfill-node')

CommonJS destructured require works; no default export.

Quickstart

Shows how to use polyfillNode plugin with esbuild, disabling Buffer/process globals and enabling crypto/fs polyfills.

import { build } from 'esbuild';
import { polyfillNode } from 'esbuild-plugin-polyfill-node';

await build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    polyfillNode({
      globals: { buffer: false, process: false },
      polyfills: { crypto: true, fs: true }
    })
  ]
});