Registry / devops / rollup-plugin-node-externals

rollup-plugin-node-externals

library9.0.1jsnpmunverified

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.

devops

npm install rollup-plugin-node-externals

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-NODE

rollup-plugin-node-externals

devopsjavascriptv9.0.1

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–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

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

default

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

✗ const nodeExternals = require('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.

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'] }) ] };

Debug

Known issues

breakingVersion 9.0.0 dropped support for Rollup 3 and Node.js < 24.

fix

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

affects: >=9.0.0

breakingVersion 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.

affects: >=9.0.0

deprecatedIn 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.

affects: 8.x

gotchaThe `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.

affects: >=8.0.0

gotchaIf 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.

affects: >=8.0.0

Errors

Common errors & fixes

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

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).

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

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'.

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

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')`.

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

Using nodeExternals without setting output.format in Rollup configuration.

fix

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

Upgrade

Version history

9.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Septh/rollup-plugin-node-externals ↗

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