Registry / devops / rollup-plugin-polyfill-node

rollup-plugin-polyfill-node

library0.13.0jsnpmunverified

The `rollup-plugin-polyfill-node` package, currently at version `0.13.0`, provides a comprehensive solution for bundling applications that rely on Node.js built-in modules with Rollup. It acts as a modern, actively maintained fork of `rollup-plugin-node-polyfills`, offering improved and more complete polyfills. The package distinguishes itself by offering ES6-specific polyfills for many modules (like `process`, `events`, `util`), enabling named imports for better tree-shaking where applicable. Its development follows a community-driven release cadence, meaning updates are dependent on contributor engagement rather than a fixed schedule. It meticulously details the level of support for each Node.js builtin, from fully shimmed modules to partial implementations and empty mocks, crucial for developers migrating Node.js codebases to browser-compatible bundles via Rollup.

devops

npm install rollup-plugin-polyfill-node

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-POLY

rollup-plugin-polyfill-node

devopsjavascriptv0.13.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nodePolyfills

✓ import nodePolyfills from 'rollup-plugin-polyfill-node';

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

Primary way to import the plugin for Rollup configuration. It's an ESM-first package, so CommonJS 'require' is not the standard or recommended approach.

Node.js Builtin Modules

✓ import { EventEmitter } from 'events';

✗ import EventEmitter from 'events';

After the plugin processes your bundle, you can import specific functions/classes from polyfilled Node.js builtins using named imports for better tree-shaking, especially for modules like 'events', 'util', 'path', 'querystring', 'punycode', 'process'.

Type imports

✓ import type { RollupNodePolyfillOptions } from 'rollup-plugin-polyfill-node';

For TypeScript users, import the configuration options type for better type safety when defining plugin options.

Demonstrates how to integrate `rollup-plugin-polyfill-node` into a Rollup configuration, showing basic plugin instantiation alongside common accompanying plugins like `resolve` and `commonjs` for proper module resolution.

import nodePolyfills from 'rollup-plugin-polyfill-node'; import commonjs from '@rollup/plugin-commonjs'; import resolve from '@rollup/plugin-node-resolve'; // Basic Rollup configuration demonstrating node polyfills export default { input: 'src/main.js', // Your main application entry point output: { file: 'dist/bundle.js', format: 'esm', // Output as ES module }, plugins: [ // Resolve node modules, important for finding polyfills resolve({ preferBuiltins: false, // Ensure polyfills are used instead of assuming native Node.js builtins browser: true, // Hint to use browser-compatible versions where available }), // CommonJS plugin to convert CommonJS modules to ES modules // This is often needed for node_modules that are not pure ESM commonjs(), // Apply the node polyfills nodePolyfills({ // Optional: include or exclude specific files. By default, it processes node_modules/**/*.js // include: [/node_modules/], // Example: explicitly include node_modules // sourceMap: true, // Enable source maps for debugging }) ] };

Debug

Known issues

gotchaThe `rollup-plugin-polyfill-node` package is entirely community-maintained. This implies that updates, bug fixes, and feature additions are reliant on community contributions, which may result in an irregular release schedule and potentially slower resolution of issues.

fix

Be prepared to contribute pull requests for issues encountered or consider alternative strategies for polyfilling critical Node.js functionalities if community support proves insufficient for your project's needs.

affects: >=0.1.0

gotchaSeveral complex Node.js built-in modules, including `http`, `https`, `stream`, `fs`, `crypto`, `vm`, and `perf_hooks`, offer only partial support or are known to have limitations. For example, `perf_hooks` is an empty shim, and `vm` has limited corner case support, especially in web worker environments.

fix

Thoroughly test any code relying on these complex polyfills. For critical functionalities, evaluate whether these modules are strictly necessary or if alternative browser-compatible solutions can be used. Review the 'Node.js Builtin Support Table' in the README for specific module caveats.

affects: >=0.1.0

gotchaA significant number of Node.js builtins, such as `dns`, `dgram`, `child_process`, `cluster`, `module`, `net`, `readline`, `repl`, and `tls`, are not fully polyfilled but instead return empty mocks. This means any code attempting to use these modules will either receive null/empty objects or throw errors at runtime.

fix

Avoid using these mocked modules in your front-end or bundled code. If your application strictly requires their functionality, consider refactoring your architecture to move such logic to a server-side component or exploring completely different libraries that offer browser-native equivalents.

affects: >=0.1.0

gotchaModules like `stream` (and anything that implicitly or explicitly relies on it, such as `http` and `https`) are known to involve complex circular references. This inherent complexity can significantly hinder Rollup's tree-shaking capabilities, leading to larger-than-expected bundle sizes.

fix

Minimize dependencies on `stream`-heavy modules where bundle size is a critical concern. Consider refactoring your code to use simpler, more tree-shakeable patterns or investigate if specific parts of these polyfills can be replaced with custom, lighter-weight shims.

affects: >=0.1.0

gotchaThe `console` polyfill only provides a default export. The documentation explicitly advises users to utilize the global `console` object directly rather than attempting to import it from the polyfill.

fix

Do not import `console` from a polyfill. Always use the globally available `console` object for logging and debugging purposes.

affects: >=0.1.0

Errors

Common errors & fixes

Module not found: Can't resolve 'fs' in '...'

A Node.js builtin module is being imported or used in a Rollup bundle without the `rollup-plugin-polyfill-node` plugin correctly configured or present.

fix

Ensure `rollup-plugin-polyfill-node` is installed and added to your Rollup configuration's `plugins` array. Verify that the plugin's `include`/`exclude` options are not preventing the polyfill from applying to the relevant files. Often, `@rollup/plugin-node-resolve` should also be used with `preferBuiltins: false`.

TypeError: (0 , vm.runInContext) is not a function

The `vm` module polyfill has limited support for all Node.js `vm` functionality, especially complex methods or specific corner cases, particularly in web worker environments.

fix

Review your usage of the `vm` module. If possible, refactor your code to avoid highly complex or specific `vm` features that may not be fully polyfilled. If `vm` is critical, consider a custom shim or re-evaluating the architectural need for `vm` in a bundled browser environment.

Observed large bundle size despite tree-shaking efforts, particularly for modules related to Node.js streams or HTTP.

Complex polyfills like `stream` (and modules that depend on it, such as `http` and `https`) contain circular references that inherently limit Rollup's tree-shaking effectiveness, leading to larger bundle sizes than expected.

fix

For critical bundle size concerns, evaluate if the specific Node.js modules are truly necessary in the bundled environment. If possible, refactor code to avoid heavy reliance on `stream`, `http`, or `https` polyfills, or consider using alternative, lighter-weight solutions or custom shims for minimal required functionality.

Upgrade

Version history

0.13.0latest on npm

Audit

Dependencies

rolluprequiredRequired by Rollup to function as a plugin.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/FredKSchott/rollup-plugin-polyfill-node ↗

packagehttps://www.npmjs.com/package/rollup-plugin-polyfill-node ↗