Rollup Plugin for Node.js Built-ins

Common errors

• (!) Missing Node.js built-in module 'punycode' (or similar built-in) ... You might need to include https://www.npmjs.com/package/rollup-plugin-node-builtins

  cause A dependency in your project or your own code is trying to import a Node.js built-in module, but `rollup-plugin-node-builtins` is either not installed, not configured, or configured incorrectly (e.g., wrong order relative to `node-globals`).
  fix Ensure `rollup-plugin-node-builtins` is installed and added to your `rollup.config.js` plugins array. If the module is one that requires `rollup-plugin-node-globals`, ensure `globals()` is before `builtins()`.

• ReferenceError: process is not defined

  cause A module in your bundle expects the global `process` object (a Node.js global), but `rollup-plugin-node-globals` (which provides shims for globals like `process` and `Buffer`) is not included or is incorrectly ordered.
  fix Install `rollup-plugin-node-globals` and add `globals()` to your Rollup plugins array, ensuring it appears *before* `builtins()`.

• TypeError: Cannot read properties of undefined (reading 'randomBytes')

  cause Attempted to use the `crypto` module without explicitly enabling it in `rollup-plugin-node-builtins` options.
  fix Enable the `crypto` shim by configuring the plugin as `builtins({ crypto: true })`.

Warnings

• breaking This package is unmaintained. The last update was in 2017 (v2.1.2). It may not be compatible with newer Rollup versions (e.g., Rollup 3+) or modern JavaScript syntax/features like dynamic imports, potentially causing build failures or runtime errors.
  Fix: Consider migrating to actively maintained alternatives like `rollup-plugin-polyfill-node` or configuring `@rollup/plugin-node-resolve` with `preferBuiltins: false` and explicitly providing browser shims, or using a more modern bundler.
• gotcha Many Node.js built-in modules (e.g., `process`, `stream`, `http`, `buffer`) require `rollup-plugin-node-globals` to be used *before* `rollup-plugin-node-builtins` in the Rollup plugin array. Failing to include or correctly order `node-globals` will result in unresolved references (`process is not defined`) for modules depending on global Node variables.
  Fix: Ensure `rollup-plugin-node-globals` is installed and placed before `rollup-plugin-node-builtins` in your `rollup.config.js` plugins array.
• gotcha Some Node.js built-in modules are not fully shimmed or have limitations. For example, `vm` has fewer corner cases handled, `http` and `https` are the same (no protocol differentiation), and modules like `dns`, `dgram`, `child_process`, `cluster`, `module`, `net`, `readline`, `repl`, and `tls` only return mocks, making them largely unusable.
  Fix: Review the plugin's README to understand the limitations of each shim. Avoid using severely limited or mock-only modules where true Node.js functionality is expected in a browser.
• gotcha The `crypto` and `fs` modules are *optional* and require explicit configuration (`{crypto: true}` or `{fs: true}`) to be enabled. Without this, attempts to `import` or `require` them will likely fail or use a basic, potentially non-functional CommonJS shim from Browserify.
  Fix: Pass `{ crypto: true }` or `{ fs: true }` as options to the `builtins()` plugin call if you intend to use these modules: `builtins({ crypto: true })`.
• gotcha Some shimmed modules, particularly `streams` and anything that depends on them (like `http`), have complex circular references which significantly hinder Rollup's tree-shaking capabilities, leading to larger-than-expected bundle sizes. `url` methods also don't tree-shake well.
  Fix: For optimal bundle size, avoid importing heavy or circular-reference-prone Node.js built-ins. If essential, perform aggressive dead code elimination (e.g., via `terser`) as a post-processing step, but be aware of its limitations for these specific modules.

Install

• npm install rollup-plugin-node-builtins npm
• yarn add rollup-plugin-node-builtins yarn
• pnpm add rollup-plugin-node-builtins pnpm

Imports

• builtins
  wrong:

  const builtins = require('rollup-plugin-node-builtins');

  correct:

  import builtins from 'rollup-plugin-node-builtins';

  While Rollup configs can be CJS, the modern practice is ESM. The plugin itself is typically imported as a default export.
• EventEmitter
  wrong:

  const EventEmitter = require('events');

  correct:

  import EventEmitter from 'events';

  For shimmed Node.js built-ins like 'events', the plugin enables them to be imported directly as if they were browser-compatible ESM modules.
• inherits
  wrong:

  import util from 'util'; const { inherits } = util;

  correct:

  import { inherits } from 'util';

  Many built-ins offer named exports (indicated by ES6 specific versions). Always prefer named imports for better tree-shaking, where available.

Quickstart

Demonstrates bundling an application that uses Node.js `http` or `events` modules for a browser environment, correctly ordering `globals` and `builtins` plugins.

import rollup from 'rollup';
import builtins from 'rollup-plugin-node-builtins';
import globals from 'rollup-plugin-node-globals';

async function build() {
  const bundle = await rollup.rollup({
    input: 'main.js',
    plugins: [
      globals(), // Must come before builtins for proper context setup
      builtins() // Enables Node.js built-ins
    ]
  });

  await bundle.write({
    file: 'bundle.js',
    format: 'iife',
    name: 'MyBundle',
    sourcemap: true
  });
  console.log('Rollup build complete!');
}

// Example main.js content for context (not part of quickstart code itself)
// import * as http from 'http';
// http.request('http://example.com');
// import { EventEmitter } from 'events';
// const emitter = new EventEmitter();

build().catch(console.error);