esbuild-node-builtin

0.1.1 verified Fri May 01 auth: no javascript

esbuild plugin to polyfill Node.js built-in modules when bundling for the browser. Version 0.1.1, stable but rarely updated. Integrates polyfills from rollup-plugin-polyfill-node with tree-shaking support, unlike alternatives that include entire modules. It uses esbuild's inject API to handle globals like 'global', 'process', and optionally 'Buffer'. Requires esbuild as a peer dependency and uses rollup-plugin-polyfill-node internally (a no-op dependency to avoid errors).

Common errors

error Error: Cannot find module 'rollup-plugin-polyfill-node' ↓

cause The package has a dependency on rollup-plugin-polyfill-node, which may not be installed if using a strict package manager or if node_modules are pruned.

fix

Ensure rollup-plugin-polyfill-node is installed (it is a regular dependency, not optional). Run: pnpm add -D esbuild-node-builtin or npm install esbuild-node-builtin --save-dev

error TypeError: esbuild_node_builtin_1.nodeBuiltin is not a function ↓

cause Using a default import instead of a named import.

fix

Use named import: import { nodeBuiltin } from 'esbuild-node-builtin'

error Error: The plugin "esbuild-node-builtin" is not a function ↓

cause Attempting to use the plugin without calling the factory function, e.g. plugins: [nodeBuiltin] instead of plugins: [nodeBuiltin()].

fix

Invoke the function: plugins: [nodeBuiltin()]

error Error: Build failed with 1 error: error: Could not resolve "crypto" ↓

cause The plugin may not cover all Node builtins, or the builtin is not polyfilled by default.

fix

Check if the builtin is polyfilled; if not, use a separate polyfill package and add to the 'exclude' option to avoid double bundling.

Warnings

gotcha The package depends on rollup-plugin-polyfill-node, but rollup is not actually needed at runtime. This can cause confusion if you try to install rollup as a dependency. ↓

fix Ignore the rollup dependency; it is used only internally. Do not install rollup unless required for other projects.

gotcha The 'injectBuffer' option is disabled by default because it is large and not tree-shakable. Enabling it may significantly increase bundle size. ↓

fix Only set injectBuffer: true if you absolutely need the Buffer global and accept the size cost.

deprecated The 'exclude' option uses a string array to disable proxying certain builtins. This API may change in future versions. ↓

fix Check the README on GitHub for the latest API if upgrading.

Install

npm install esbuild-node-builtin

yarn add esbuild-node-builtin

pnpm add esbuild-node-builtin

Imports

nodeBuiltin

wrong

import nodeBuiltin from 'esbuild-node-builtin'

correct

import { nodeBuiltin } from 'esbuild-node-builtin'

Exported as named export only; default import will not work.

nodeBuiltin
wrong
```
const nodeBuiltin = require('esbuild-node-builtin')
```
correct
```
const { nodeBuiltin } = require('esbuild-node-builtin')
```
CJS require destructuring is required; plain require returns an object with the named export.
EsbuildNodeBuiltinOptions
```
import type { EsbuildNodeBuiltinOptions } from 'esbuild-node-builtin'
```
Type import for the options interface; only needed with TypeScript.

Quickstart

Demonstrates basic usage of the plugin with esbuild bundling for browser, using default options to polyfill 'global' and 'process'.

import { nodeBuiltin } from 'esbuild-node-builtin';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  platform: 'browser',
  plugins: [nodeBuiltin()],
});