rollup-plugin-node-externals

A Rollup plugin that automatically declares NodeJS built-in modules as external. Also handles npm dependencies, devDependencies, peerDependencies and optionalDependencies.

Works in monorepos too!

Breaking changes in version 5

• In previous versions, the devDeps option (see below) defaulted to true.
  This was practical, but often wrong: devDependencies are ment just for that: being used when developping. Therefore, the devDeps option now defaults to false, meaning Rollup will include them in your bundle.
• As anticipated since v4, the builtinsPrefix option now defaults to 'add'.
• The deprecated prefixedBuiltins option has been removed.
• rollup-plugin-node-externals no longer depends on the Find Up package. While this is not a breaking change per se, it can be in some edge situations.

Why you need this

Installation

Use your favorite package manager. Mine is npm.

npm install --save-dev rollup-plugin-node-externals

Usage

When bundling an application or library, you want to have your runtime dependencies listed under dependencies in package.json, and development dependencies listed under devDependencies.

If you follow this simple rule, then the built-in defaults are just what you need:

export default {
  ...
  plugins: [
    externals(),
  ]
}

• Or, if you'd rather bundle dependencies in:

export default {
  ...
  plugins: [
    externals({
      deps: false,    // Dependencies will be bundled in
    }),
  ]
}

Options

All options are, well, optional.

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

export default {
  ...
  plugins: [
    externals({

      // Make node builtins external. Default: true.
      builtins?: boolean

      // node: prefix handing for importing Node builtins. Default: 'add'.
      builtinsPrefix?: 'add' | 'strip'

      // The path(s) to your package.json. See below for default.
      packagePath?: string | string[]

      // Make pkg.dependencies external. Default: true.
      deps?: boolean

      // Make pkg.devDependencies external. Default: false.
      devDeps?: boolean

      // Make pkg.peerDependencies external. Default: true.
      peerDeps?: boolean

      // Make pkg.optionalDependencies external. Default: true.
      optDeps?: boolean

      // Modules to force include in externals. Default: [].
      include?: string | RegExp | (string | RegExp)[]

      // Modules to force exclude from externals. Default: [].
      exclude?: string | RegExp | (string | RegExp)[]
    })
  ]
}

builtins?: boolean = true

Set the builtins option to false if you'd like to use some shims/polyfills for those. You'll most certainly need an other plugin for this.

builtinsPrefix?: 'add' | 'strip' = 'add'

How to handle the node: scheme used in recent versions of Node (i.e., import path from 'node:path').
Note that prefix handling is independant of the builtins options being enabled or disabled.

• If add (the default), the node: prefix is always added. In effect, this homogenizes all your imports of node builtins to their prefixed version.
• If strip (the default), the import is always resolved unprefixed. In effect, this homogenizes all your imports of node builtins to their unprefixed version.

packagePath?: string | string[] = []

If you're working with monorepos, the packagePath option 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.

deps?: boolean = true

devDeps?: boolean = false

peerDeps?: boolean = true

optDeps?: boolean = true

Set the deps, devDeps, peerDeps and optDeps options to false to prevent the corresponding dependencies from being externalized, therefore letting Rollup bundle them with your code.

include?: string | RegExp | (string | RegExp)[] = []

exclude?: string | RegExp | (string | RegExp)[] = []

Use the include option to force certain dependencies into the list of externals:

externals({
  deps: false,                // Deps will be bundled in
  include: /^fsevents/        // Except for fsevents
})

Conversely, use the exclude option to remove certain dependencies from the list of externals:

externals({
  deps: true,                 // Deps are external
  exclude: 'electron-reload'  // Yet we want `electron-reload` bundled in
})

Notes

1/ This plugin is smart

Falsy values in include and exclude are silently ignored. This allows for conditional constructs like exclude: process.env.NODE_ENV === 'production' && 'my-prod-only-dep'.

2/ This plugin is not that smart

It uses an exact match against your imports, so if your are using some kind of path substitution in your code, eg.:

// In your code, say '@/' is mapped to some directory:
import something from '@/mylib'

and you don't want mylib bundled in, then write:

// In rollup.config.js:
externals({
    include: '@/mylib'
})

However, subpath imports are supported with regexes, meaning that include: /^lodash/ will externalize lodash and also lodash/map, lodash/merge, etc.

3/ Order matters

If you're also using @rollup/plugin-node-resolve, make sure this plugin comes before it in the plugins array:

import externals from 'rollup-plugin-node-externals'
import resolve from '@rollup/plugin-node-resolve'

export default {
  ...
  plugins: [
    externals(),
    resolve(),
  ]
}

As a general rule of thumb, you might want to always make this plugin the first one in the plugins array.

4/ Rollup rules

Rollup's own external configuration option always takes precedence over this plugin. This is intentional.

Licence

MIT