# @stackline/rollup-plugin-polyfill-node
> Compatibility-first Rollup polyfills for supported Node.js built-ins in browsers.
[](https://www.npmjs.com/package/@stackline/rollup-plugin-polyfill-node)
[](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node)
[](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node)
[](https://alexandro.net/docs/vanilla/rollup-plugin-polyfill-node/)
[](https://www.reddit.com/r/Stackline/)
**[Documentation](https://alexandro.net/docs/vanilla/rollup-plugin-polyfill-node/)** | **[npm](https://www.npmjs.com/package/@stackline/rollup-plugin-polyfill-node)** | **[Issues](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/issues)** | **[Repository](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node)**
**Current package version:** `1.0.4`
---
## Why this package?
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`](https://github.com/FredKSchott/rollup-plugin-polyfill-node),
which in turn derives from
[`ionic-team/rollup-plugin-node-polyfills`](https://github.com/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](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/NOTICE), [THIRD_PARTY_NOTICES.md](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/THIRD_PARTY_NOTICES.md),
and [LICENSE.md](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/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](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/SUPPORT_MATRIX.md) before relying on a module or export.
## Compatibility
| Item | Value |
| --- | --- |
| Package | `@stackline/rollup-plugin-polyfill-node@1.0.4` |
| Node.js runtime | `>=14.0.0` |
| CommonJS / primary entry | `./dist/index.js` |
| ES module entry | `./dist/es/index.js` |
| Type declarations | `./dist/index.d.cts` |
## Installation
### Install
```bash
npm install --save-dev @stackline/rollup-plugin-polyfill-node
```
## Usage
The package supports Node.js 14 or newer and Rollup `^1.20.0`, `^2`, `^3`, or
`^4`.
```js
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:
```js
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](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/MIGRATION.md) and remove that workaround only after comparing
the resulting bundle and browser tests.
## Features and Integrations
### 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](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/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:
```json
{
"devDependencies": {
"rollup-plugin-polyfill-node": "npm:@stackline/rollup-plugin-polyfill-node@^1.0.2"
}
}
```
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](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/MIGRATION.md).
## Security
### Security and contributions
Report suspected vulnerabilities privately as described in
[SECURITY.md](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/SECURITY.md). For build, test, provenance, and compatibility
requirements, see [CONTRIBUTING.md](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/blob/main/CONTRIBUTING.md).
## API Surface
### Options
All options are optional.
```ts
interface NodePolyfillsOptions {
baseDir?: string;
crypto?: boolean;
sourceMap?: boolean;
include?: Array | string | RegExp | null;
exclude?: Array | 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.
## Local Development
```sh
git clone https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node.git
cd stackline-rollup-plugin-polyfill-node
npm ci
npm run verify
```
Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.
## Consumer Smoke Test
Run the repository's existing consumer/package check after installing development dependencies:
```sh
npm run check:packed
```
## Release Checklist
Run `npm run verify` and inspect the package contents before release. Publish a new version through the [GitHub Actions publishing workflow](https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/actions/workflows/publish.yml), using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.
## 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.
Dependency maintenance for this release is documented in [DEPENDENCY_UPDATES.md](DEPENDENCY_UPDATES.md).
## Credits and original authors
- Original project: [rollup-plugin-polyfill-node](https://github.com/FredKSchott/rollup-plugin-polyfill-node).
- Stackline maintainers.
- Fred K. Schott.
- Ionic Team rollup-plugin-node-polyfills contributors.
- Copyright (c) 2020 Fred K. Schott.
- Copyright (c) 2019 these people.
- Copyright (c) 2019 these people (Ionic-origin code).
- Stackline maintenance: [Alexandro Paixao Marques](https://www.linkedin.com/in/aleinfo/) and [Stackline contributors](https://github.com/alexandroit).
Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.
## Community and Links
- [Stackline website](https://alexandro.net/)
- [GitHub projects](https://github.com/alexandroit)
- [npm packages](https://www.npmjs.com/~alex360qc)
- [Reddit community — r/Stackline](https://www.reddit.com/r/Stackline/)
- [Maintainer LinkedIn](https://www.linkedin.com/in/aleinfo/)
Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.
Documentation-only release: runtime file bytes and dependencies are unchanged from 1.0.2.
Release: https://github.com/alexandroit/stackline-rollup-plugin-polyfill-node/releases/tag/docs-stackline-rollup-plugin-polyfill-node-v1.0.4