{"id":11958,"library":"rollup-plugin-polyfill-node","title":"Rollup Plugin for Node.js Polyfills","description":"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.","status":"active","version":"0.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/FredKSchott/rollup-plugin-polyfill-node","tags":["javascript","rollup-plugin","typescript"],"install":[{"cmd":"npm install rollup-plugin-polyfill-node","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-polyfill-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-polyfill-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required by Rollup to function as a plugin.","package":"rollup","optional":false}],"imports":[{"note":"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.","wrong":"const nodePolyfills = require('rollup-plugin-polyfill-node');","symbol":"nodePolyfills","correct":"import nodePolyfills from 'rollup-plugin-polyfill-node';"},{"note":"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'.","wrong":"import EventEmitter from 'events';","symbol":"Node.js Builtin Modules","correct":"import { EventEmitter } from 'events';"},{"note":"For TypeScript users, import the configuration options type for better type safety when defining plugin options.","symbol":"Type imports","correct":"import type { RollupNodePolyfillOptions } from 'rollup-plugin-polyfill-node';"}],"quickstart":{"code":"import nodePolyfills from 'rollup-plugin-polyfill-node';\nimport commonjs from '@rollup/plugin-commonjs';\nimport resolve from '@rollup/plugin-node-resolve';\n\n// Basic Rollup configuration demonstrating node polyfills\nexport default {\n  input: 'src/main.js', // Your main application entry point\n  output: {\n    file: 'dist/bundle.js',\n    format: 'esm', // Output as ES module\n  },\n  plugins: [\n    // Resolve node modules, important for finding polyfills\n    resolve({\n      preferBuiltins: false, // Ensure polyfills are used instead of assuming native Node.js builtins\n      browser: true, // Hint to use browser-compatible versions where available\n    }),\n    // CommonJS plugin to convert CommonJS modules to ES modules\n    // This is often needed for node_modules that are not pure ESM\n    commonjs(),\n    // Apply the node polyfills\n    nodePolyfills({\n      // Optional: include or exclude specific files. By default, it processes node_modules/**/*.js\n      // include: [/node_modules/], // Example: explicitly include node_modules\n      // sourceMap: true, // Enable source maps for debugging\n    })\n  ]\n};","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Several 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"A 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Modules 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Do not import `console` from a polyfill. Always use the globally available `console` object for logging and debugging purposes.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"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.","error":"Module not found: Can't resolve 'fs' in '...'"},{"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.","cause":"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.","error":"TypeError: (0 , vm.runInContext) is not a function"},{"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.","cause":"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.","error":"Observed large bundle size despite tree-shaking efforts, particularly for modules related to Node.js streams or HTTP."}],"ecosystem":"npm"}