{"id":11956,"library":"rollup-plugin-node-builtins","title":"Rollup Plugin for Node.js Built-ins","description":"This Rollup plugin shims Node.js built-in modules, enabling projects designed for a Node.js environment or Browserify to run in a browser bundle. It allows `require` or `import` statements for modules like `events`, `util`, `path`, and `buffer` to be resolved during the Rollup bundling process. The latest stable version is 2.1.2, released in 2017. Due to its age, it is no longer actively maintained and may have compatibility issues with newer Rollup versions or modern JavaScript features. For many built-ins (marked with an asterisk in the README), it requires the companion `rollup-plugin-node-globals` for proper functionality, especially for `process` and `Buffer`. Key differentiators at the time of its release were its ability to provide Browserify-compatible shims within the Rollup ecosystem, bridging a gap for projects with existing Node.js module dependencies. However, more modern alternatives like `@rollup/plugin-node-resolve` (with specific configuration) or `rollup-plugin-polyfill-node` are now generally recommended.","status":"abandoned","version":"2.1.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/calvinmetcalf/rollup-plugin-node-builtins","tags":["javascript","rollup-plugin"],"install":[{"cmd":"npm install rollup-plugin-node-builtins","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-node-builtins","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-node-builtins","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for many built-in modules like 'process', 'stream', 'util', 'buffer', 'http', 'https', 'os', 'assert', 'timers', 'console', 'vm', 'zlib', and 'fs' to be properly shimmed in the browser environment.","package":"rollup-plugin-node-globals","optional":false}],"imports":[{"note":"While Rollup configs can be CJS, the modern practice is ESM. The plugin itself is typically imported as a default export.","wrong":"const builtins = require('rollup-plugin-node-builtins');","symbol":"builtins","correct":"import builtins from 'rollup-plugin-node-builtins';"},{"note":"For shimmed Node.js built-ins like 'events', the plugin enables them to be imported directly as if they were browser-compatible ESM modules.","wrong":"const EventEmitter = require('events');","symbol":"EventEmitter","correct":"import EventEmitter from 'events';"},{"note":"Many built-ins offer named exports (indicated by ES6 specific versions). Always prefer named imports for better tree-shaking, where available.","wrong":"import util from 'util'; const { inherits } = util;","symbol":"inherits","correct":"import { inherits } from 'util';"}],"quickstart":{"code":"import rollup from 'rollup';\nimport builtins from 'rollup-plugin-node-builtins';\nimport globals from 'rollup-plugin-node-globals';\n\nasync function build() {\n  const bundle = await rollup.rollup({\n    input: 'main.js',\n    plugins: [\n      globals(), // Must come before builtins for proper context setup\n      builtins() // Enables Node.js built-ins\n    ]\n  });\n\n  await bundle.write({\n    file: 'bundle.js',\n    format: 'iife',\n    name: 'MyBundle',\n    sourcemap: true\n  });\n  console.log('Rollup build complete!');\n}\n\n// Example main.js content for context (not part of quickstart code itself)\n// import * as http from 'http';\n// http.request('http://example.com');\n// import { EventEmitter } from 'events';\n// const emitter = new EventEmitter();\n\nbuild().catch(console.error);","lang":"javascript","description":"Demonstrates bundling an application that uses Node.js `http` or `events` modules for a browser environment, correctly ordering `globals` and `builtins` plugins."},"warnings":[{"fix":"Consider migrating to actively maintained alternatives like `rollup-plugin-polyfill-node` or configuring `@rollup/plugin-node-resolve` with `preferBuiltins: false` and explicitly providing browser shims, or using a more modern bundler.","message":"This package is unmaintained. The last update was in 2017 (v2.1.2). It may not be compatible with newer Rollup versions (e.g., Rollup 3+) or modern JavaScript syntax/features like dynamic imports, potentially causing build failures or runtime errors.","severity":"breaking","affected_versions":">=2.1.2"},{"fix":"Ensure `rollup-plugin-node-globals` is installed and placed before `rollup-plugin-node-builtins` in your `rollup.config.js` plugins array.","message":"Many Node.js built-in modules (e.g., `process`, `stream`, `http`, `buffer`) require `rollup-plugin-node-globals` to be used *before* `rollup-plugin-node-builtins` in the Rollup plugin array. Failing to include or correctly order `node-globals` will result in unresolved references (`process is not defined`) for modules depending on global Node variables.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the plugin's README to understand the limitations of each shim. Avoid using severely limited or mock-only modules where true Node.js functionality is expected in a browser.","message":"Some Node.js built-in modules are not fully shimmed or have limitations. For example, `vm` has fewer corner cases handled, `http` and `https` are the same (no protocol differentiation), and modules like `dns`, `dgram`, `child_process`, `cluster`, `module`, `net`, `readline`, `repl`, and `tls` only return mocks, making them largely unusable.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass `{ crypto: true }` or `{ fs: true }` as options to the `builtins()` plugin call if you intend to use these modules: `builtins({ crypto: true })`.","message":"The `crypto` and `fs` modules are *optional* and require explicit configuration (`{crypto: true}` or `{fs: true}`) to be enabled. Without this, attempts to `import` or `require` them will likely fail or use a basic, potentially non-functional CommonJS shim from Browserify.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For optimal bundle size, avoid importing heavy or circular-reference-prone Node.js built-ins. If essential, perform aggressive dead code elimination (e.g., via `terser`) as a post-processing step, but be aware of its limitations for these specific modules.","message":"Some shimmed modules, particularly `streams` and anything that depends on them (like `http`), have complex circular references which significantly hinder Rollup's tree-shaking capabilities, leading to larger-than-expected bundle sizes. `url` methods also don't tree-shake well.","severity":"gotcha","affected_versions":">=1.0.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-node-builtins` is installed and added to your `rollup.config.js` plugins array. If the module is one that requires `rollup-plugin-node-globals`, ensure `globals()` is before `builtins()`.","cause":"A dependency in your project or your own code is trying to import a Node.js built-in module, but `rollup-plugin-node-builtins` is either not installed, not configured, or configured incorrectly (e.g., wrong order relative to `node-globals`).","error":"(!) Missing Node.js built-in module 'punycode' (or similar built-in) ... You might need to include https://www.npmjs.com/package/rollup-plugin-node-builtins"},{"fix":"Install `rollup-plugin-node-globals` and add `globals()` to your Rollup plugins array, ensuring it appears *before* `builtins()`.","cause":"A module in your bundle expects the global `process` object (a Node.js global), but `rollup-plugin-node-globals` (which provides shims for globals like `process` and `Buffer`) is not included or is incorrectly ordered.","error":"ReferenceError: process is not defined"},{"fix":"Enable the `crypto` shim by configuring the plugin as `builtins({ crypto: true })`.","cause":"Attempted to use the `crypto` module without explicitly enabling it in `rollup-plugin-node-builtins` options.","error":"TypeError: Cannot read properties of undefined (reading 'randomBytes')"}],"ecosystem":"npm"}