rollup-plugin-node-externals

9.0.1 verified Mon Apr 27 auth: no javascript

A Rollup/Vite plugin that automatically marks Node.js built-in modules and npm dependencies (dependencies, peerDependencies, optionalDependencies, or devDependencies) as external in your bundle configuration. Version 9.0.1 is the latest stable release, released monthly, requiring Node.js >= 24 and Rollup >= 4 or Vite >= 5. It is zero-dependency, lightweight (<10 kB), and supports monorepos and all package managers. Compared to alternatives like rollup-plugin-auto-external, it offers finer-grained control over which dependency categories to externalize and includes options for handling the node: prefix on builtins.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/rollup-plugin-node-externals/dist/index.mjs not supported. ↓

cause Attempting to use CommonJS require() to import an ESM-only package.

fix

Replace require() with import: use import nodeExternals from 'rollup-plugin-node-externals' and configure your project for ESM (e.g., add "type": "module" in package.json).

error rollup-plugin-node-externals: Option `builtinsPrefix` must be one of 'add', 'strip', 'ignore', true, or false. ↓

cause Passing an invalid value to the builtinsPrefix option (e.g., a string like 'keep' or a number).

fix

Use one of the valid values: 'add' (or true), 'strip' (or false), or 'ignore'.

error rollup-plugin-node-externals: Could not find package.json at path /some/path ↓

cause The packagePath option points to a non-existent file or a directory, not a package.json.

fix

Provide an absolute path to the actual package.json file: packagePath: path.resolve(__dirname, 'package.json').

error (!) RollupOptions `output.format` must be set when not in watch mode ↓

cause Using nodeExternals without setting output.format in Rollup configuration.

fix

Set output.format (e.g., 'cjs', 'esm', 'iife') in your Rollup config.

Warnings

breaking Version 9.0.0 dropped support for Rollup 3 and Node.js < 24. ↓

fix Upgrade to Rollup 4+ and Node.js 24+.

breaking Version 9.0.0 changed the default value of `builtinsPrefix` option from 'add' to 'add' (no change) but accepts boolean `true` as 'add' and `false` as 'strip'. ↓

fix If using `builtinsPrefix: false`, it now strips the prefix (equivalent to 'strip'). Use `builtinsPrefix: 'ignore'` to ignore prefix entirely.

deprecated In version 8.x, the plugin factory was asynchronous; in 9.0.0 it is synchronous again. ↓

fix Remove async/await from plugin creation; revert to synchronous factory.

gotcha The `packagePath` option expects path(s) to a `package.json` file, not a directory. Incorrect paths cause the plugin to silently not externalize dependencies. ↓

fix Use `path.resolve(__dirname, 'package.json')` or absolute paths to the package.json file.

gotcha If using Vite, the plugin is not applied to the dev server; it only affects the build phase. This may cause differences in resolution between dev and build. ↓

fix Use Vite's `apply: 'build'` property in the plugin options or manually check the environment.

Install

npm install rollup-plugin-node-externals

yarn add rollup-plugin-node-externals

pnpm add rollup-plugin-node-externals

Imports

default

wrong

const nodeExternals = require('rollup-plugin-node-externals')

correct

import nodeExternals from 'rollup-plugin-node-externals'

ESM-only; CommonJS require will fail with ERR_REQUIRE_ESM.

nodeExternals
```
import { nodeExternals } from 'rollup-plugin-node-externals'
```
Named export also available; both default and named exports reference the same factory function.
nodeExternals (type)
```
import type { NodeExternalsOptions } from 'rollup-plugin-node-externals'
```
TypeScript users: types are shipped with the package; import for options typing.

Quickstart

Basic Rollup config using nodeExternals to externalize Node builtins and runtime dependencies, excluding a local module from externalization.

// rollup.config.js
import nodeExternals from 'rollup-plugin-node-externals';

export default {
  input: 'src/index.js',
  output: { dir: 'dist', format: 'cjs' },
  plugins: [
    nodeExternals({
      builtins: true,
      deps: true,
      devDeps: false,
      peerDeps: true,
      optDeps: true,
      builtinsPrefix: 'add',
      exclude: ['my-local-module']
    })
  ]
};