Rollup Plugin for Node.js Polyfills (Legacy)

Common errors

• Module not found: Can't resolve 'events'

  cause A Node.js built-in module is being imported or required in a Rollup bundle without `rollup-plugin-node-polyfills` being configured or the specific polyfill failing.
  fix Ensure `rollup-plugin-node-polyfills` is correctly installed and added to your Rollup plugins array. If using a specific module like `crypto` or `fs`, ensure it's explicitly enabled via plugin options. Consider migrating to `rollup-plugin-polyfill-node`.

• TypeError: process.nextTick is not a function

  cause Code relies on a `process` API (`process.nextTick`) that is either not fully polyfilled or the `process` polyfill isn't correctly applied.
  fix Verify the plugin is active and correctly processes files where `process` is used. For modern projects, it's recommended to use `rollup-plugin-polyfill-node` for better `process` polyfill support.

• Uncaught ReferenceError: Buffer is not defined

  cause The `Buffer` global or import is not being correctly provided by the polyfill, or code is attempting to use `Buffer` without importing it explicitly.
  fix Ensure `import { Buffer } from 'buffer';` is present where `Buffer` is used. Verify the `buffer` polyfill is active through the plugin. Consider using a newer polyfill plugin if issues persist.

• TypeError: require is not a function

  cause Your bundled code (intended for the browser) contains `require()` calls for Node.js modules, and the plugin failed to transform them into browser-compatible imports.
  fix Confirm the plugin is enabled and configured to process all relevant files (`include` option). For better reliability, especially in modern Rollup setups, use `import` statements over `require()` where possible and upgrade to `rollup-plugin-polyfill-node`.

Warnings

• breaking This package, `rollup-plugin-node-polyfills` (from Ionic Team), is abandoned and has not been updated since version `0.2.1` (last published June 2019). It is not actively maintained and may have unaddressed bugs or security vulnerabilities.
  Fix: Migrate to `rollup-plugin-polyfill-node` (a community-maintained fork) for active development and better Node.js polyfills, or `@frida/rollup-plugin-node-polyfills` if your project specifically uses Frida's shims.
• gotcha The `crypto` module is not effectively shimmed by default and provides limited functionality, primarily from a browserify CommonJS shim.
  Fix: Pass `{crypto: true}` as an option to the plugin to enable the browserified shim, but be aware that full `crypto` functionality is unlikely to be available in a browser environment.
• gotcha Modules such as `http`, `https`, and `stream` contain circular references, which can significantly hinder tree-shaking and lead to larger bundle sizes.
  Fix: Carefully evaluate dependencies on these modules. If possible, refactor code to avoid them or explore alternative browser-native solutions. Be aware of the potential for larger bundles if these modules are included.
• gotcha Several Node.js modules (e.g., `dns`, `dgram`, `child_process`, `cluster`, `module`, `net`, `readline`, `repl`, `tls`) are not truly shimmed; they only return mock objects, rendering their functionality essentially unavailable in the browser environment.
  Fix: Avoid relying on these modules entirely when targeting browser environments with this plugin. These APIs are inherently Node.js-specific and generally cannot be meaningfully polyfilled in a browser.
• gotcha The `fs` (file system) module's browserified shim is optional and not included by default.
  Fix: Enable the `fs` shim explicitly by passing `{fs: true}` as an option to the plugin if you require its limited browser-compatible functionality.
• gotcha The `vm` module has known limitations and does not support all corner cases, especially when used in web workers.
  Fix: Test `vm` module usage thoroughly in your target environments and consider its inherent limitations for complex or security-sensitive scenarios.

Install

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

Imports

• nodePolyfills
  wrong:

  const nodePolyfills = require('rollup-plugin-node-polyfills');

  correct:

  import nodePolyfills from 'rollup-plugin-node-polyfills';

  Rollup configuration files are typically written in ESM, so `import` syntax is preferred. CommonJS `require` is generally not used for plugin imports in modern Rollup setups.
• EventEmitter
  wrong:

  const EventEmitter = require('events');

  correct:

  import EventEmitter from 'events';

  The plugin provides ES6 specific versions for many modules, allowing named imports or default imports for common patterns like `EventEmitter` from `events`. While `require` might technically work in the bundled output for some cases, using `import` is idiomatic for ES modules.
• inherits
  wrong:

  import util from 'util'; const inherits = util.inherits;

  correct:

  import { inherits } from 'util';

  For modules that tree-shake well (like `util`), named imports for specific functions like `inherits` are efficient and supported by the plugin.
• Buffer
  wrong:

  const Buffer = require('buffer').Buffer;

  correct:

  import { Buffer } from 'buffer';

  When using the `buffer` polyfill, `Buffer` is typically imported as a named export. The plugin aims to provide ES6-compatible access.

Quickstart

Demonstrates a basic Rollup configuration using the `nodePolyfills` plugin and shows how to import and use a few polyfilled Node.js built-in modules like `events`, `util`, and `buffer` in the `main.js` entry point.

import nodePolyfills from 'rollup-plugin-node-polyfills';
import EventEmitter from 'events';
import { inherits } from 'util';
import { Buffer } from 'buffer';

const eventEmitter = new EventEmitter();
console.log(eventEmitter instanceof EventEmitter);

class MyClass {}
inherits(MyClass, EventEmitter);
const myInstance = new MyClass();
console.log(myInstance instanceof EventEmitter);

const buf = Buffer.from('hello');
console.log(buf.toString());

export default {
  input: 'main.js',
  output: {
    file: 'bundle.js',
    format: 'esm'
  },
  plugins: [
    nodePolyfills()
  ]
};