A Rollup plugin that automatically declares NodeJS built-in modules as
external. Can also handle npm dependencies, devDependencies, peerDependencies and optionalDependencies. Works in monorepos too!
By default, Rollup doesn't know a thing about NodeJS, so trying to bundle simple things like
import * as path from 'path' in your code generates an
Unresolved dependencies error. The solution here is twofold:
- Either use some kind of shim like those provided by rollup-plugin-node-builtins.
- Or tell Rollup that the
pathmodule is in fact
external: this way, Rollup won't try to bundle it in and rather leave the
importstatement as is (or translate it to a
require()call if bundling for CommonJS).
However, this must be done for each and every NodeJS built-in:
fs, etc., which can quicky become cumbersome when done manually. So the primary goal of this plugin is simply to automatically declare all NodeJS built-in modules as
Note: the list of builtins is obtained via the builtin-modules package by Sindre Sorhus and should be up-to-date with your current NodeJS version.
This plugin will also allow you to declare your dependencies (as declared in your
package.json file) as
external. This may come in handy when building an Electron app, for example.
npm install --save-dev rollup-plugin-node-externals
input: ...output: ...plugins:
Most of the time, the built-in defaults are just what you need:
// ...plugins:// Bundle deps in; make all Node builtins, devDeps, peerDeps and optDeps external
Note: if you're also using
@rollup/plugin-node-resolve, make sure this plugin comes before it in the
// ...// ...plugins:// other plugins
By default, the plugin will mark all Node builtin modules and all your
optionalDependencies as external. Normal
dependencies are left unmarked so Rollup will still bundle them with your code as expected in most situations.
- packagePath?: string | string = 
If you're working with monorepos, the
packagePath is made for you. It can take a path, or an array of paths, to your package.json file(s). If not specified, the default is to start with the current directory's package.json then go up scan for all package.json files in parent directories recursively until either the root git directory is reached or until no other package.json can be found.
- builtins?: boolean = true
- deps?: boolean = false
- devDeps?: boolean = true
- peerDeps?: boolean = true
- optDeps?: boolean = true
optDeps options to
false to prevent the corresponding dependencies from being externalized, therefore letting Rollup bundle them with your code. Set them to
true for Rollup to treat the corresponding dependencies as external.
- include?: string | RegExp | (string | RegExp) = 
- exclude?: string | RegExp | (string | RegExp) = 
exclude option to remove certain dependencies from the list of externals, for example:
include option to force certain dependencies into the list of externals, for example:
Note 1 : falsy values in
excludeare silently ignored. This allows for conditional constructs like so:
exclude: process.env.NODE_ENV === 'production' && /mydep/.
Note2 : this plugin uses an exact match against your imports, so if your are using some path substitution in your code, eg.:
// in your code, say '@/' is mapped to some directory:
and you don't want
mylib bundled in, then write:
// in rollup.config.js:
Migrating from version 1.x
- In 1.x, normal dependencies were externalized by default. This is no more true, so you'll need to change:
if you want the same behavior.
- For consistency with all other Rollup plugins out there, the
exceptoption from 1.x is now deprecated in favor of the Rollup-friendly
excludeoption. It will be removed in the next major release but is still accepted for backward compatibility and works exactly the same as
excludebut it will issue a warning if used. To suppress this warning, just replace