@stackline/rollup-plugin-polyfill-node

Compatibility-focused Rollup polyfills for a documented subset of Node.js built-in modules in browser bundles.

This package is an independent, Stackline-maintained derivative of rollup-plugin-polyfill-node, which in turn derives from ionic-team/rollup-plugin-node-polyfills. It is not affiliated with or endorsed by Fred K. Schott, Ionic, Rollup, Node.js, or the OpenJS Foundation. Their names identify upstream projects only. See NOTICE, THIRD_PARTY_NOTICES.md, and LICENSE.md for provenance and license information.

Why this derivative exists

The historical 0.13.0 package has useful, widely deployed browser polyfills, but it does not resolve supported node: imports and several documented Node exports are absent. This derivative keeps the proven Rollup plugin contract while making its boundary explicit:

• bare and node:-prefixed imports resolve identically for supported built-ins;
• url.urlToHttpOptions, a bounded util.types, and util.formatWithOptions are available as named exports;
• fs and, by default, crypto fail during resolution instead of becoming silent empty modules;
• __filename and __dirname are injected as distinct POSIX-style values;
• the constants corpus is frozen, reviewed input rather than a snapshot of the machine that happened to build the package; and
• CommonJS and ESM plugin entry points are shipped and tested from the packed artifact.

This is a browser compatibility layer, not a Node.js runtime. Review the support matrix before relying on a module or export.

Install

npm install --save-dev @stackline/rollup-plugin-polyfill-node

The package supports Node.js 14 or newer and Rollup ^1.20.0, ^2, ^3, or ^4.

import nodePolyfills from '@stackline/rollup-plugin-polyfill-node';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'es'
  },
  plugins: [nodePolyfills()]
};

CommonJS configuration is also supported:

const loaded = require('@stackline/rollup-plugin-polyfill-node');
const nodePolyfills = loaded.default || loaded;

module.exports = {
  input: 'src/index.js',
  plugins: [nodePolyfills()]
};

Place this plugin before plugins that need to consume the resolved polyfill modules. If an alias plugin currently strips node:, follow MIGRATION.md and remove that workaround only after comparing the resulting bundle and browser tests.

Options

All options are optional.

interface NodePolyfillsOptions {
  baseDir?: string;
  crypto?: boolean;
  sourceMap?: boolean;
  include?: Array<string | RegExp> | string | RegExp | null;
  exclude?: Array<string | RegExp> | string | RegExp | null;
}

• baseDir controls the base used for injected __dirname and __filename values. It defaults to /.
• crypto defaults to false. Strict true restores the historical empty crypto shim for migration only; it does not implement any crypto export.
• include controls global injection by @rollup/plugin-inject. The default is node_modules/**/*.js. Pass null to include application source too.
• exclude removes matching files from global injection.
• sourceMap enables or disables source maps produced by the injection pass.

The include and exclude options affect injected globals such as Buffer and process; they do not turn unsupported Node built-ins into supported ones.

Supported surface

The main supported module families are assert, buffer, constants, events, http, https, os, path, process, punycode, querystring, stream, string_decoder, timers, tty, url, util, vm, and zlib. Several have browser-specific caveats. util/types is deliberately limited to isDate, isMap, isNativeError, and isRegExp.

Server-only modules such as fs, crypto, child_process, net, and tls are unsupported. fs and default crypto imports fail with UNSUPPORTED_NODE_BUILTIN for bare and node: spellings, including namespace and side-effect imports. Provide an explicit browser implementation or mark the module external only when the target runtime supplies it. This package does not pretend that browser storage is Node's filesystem, and it does not ship the historical crypto-browserify snapshot. The complete classification, including legacy empty placeholders, is in SUPPORT_MATRIX.md.

Migration from the historical package

You can change imports to the scoped package or keep the historical dependency key with an npm alias:

{
  "devDependencies": {
    "rollup-plugin-polyfill-node": "npm:@stackline/rollup-plugin-polyfill-node@^1.0.0"
  }
}

The alias form lets existing import nodePolyfills from 'rollup-plugin-polyfill-node' statements remain unchanged while the lockfile resolves the maintained scoped artifact. Exact commands, behavioral changes, and rollback guidance are in MIGRATION.md.

Security and contributions

Report suspected vulnerabilities privately as described in SECURITY.md. For build, test, provenance, and compatibility requirements, see CONTRIBUTING.md.

License

The plugin source is MIT licensed. Vendored polyfills retain their original notices and, where applicable, additional license terms. Distributing a bundle produced with this plugin may copy polyfill code into that bundle; downstream distributors are responsible for retaining the applicable notices.