# rollup-plugin-node-externals
A Rollup/Vite plugin that automatically declares NodeJS built-in modules and npm dependencies as `external`.
- Ultra-lightweight: less than 10 kB download, less than 25 kB unpacked.
- Zero runtime dependencies.
- Works in monorepos.
- Works with all package managers.
## Why you need this
(click to read if you're wondering)
By default, Rollup doesn't know a thing about NodeJS, so trying to bundle simple things like `import path from 'node:path'` in your code results in an `Unresolved dependencies` warning.
The solution here is quite simple: you must tell Rollup that the `node:path` module is in fact _external_. This way, Rollup won't try to bundle it in and rather leave the `import` statement 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 you happen to use in your program: `node:path`, `node:os`, `node:fs`, `node:url`, etc., which can quickly become cumbersome when done manually.
So the primary goal of this plugin is simply to automatically declare all NodeJS built-in modules as external. As an added bonus, this plugin will also declare your dependencies (as per your local or monorepo `package.json` file(s)) as external.
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/Vite bundle them with your code.
#### include?: string | RegExp | (string | RegExp)[] = []
Use the `include` option to force include certain dependencies into the list of externals regardless of other settings:
```js
nodeExternals({
deps: false, // Deps will be bundled in
include: 'some-dep' // Except for 'some-dep'
})
```
#### exclude?: string | RegExp | (string | RegExp)[] = []
Conversely, use the `exclude` option to remove certain dependencies from the list of externals regardless of other settings:
```js
nodeExternals({
deps: true, // Keep deps external
exclude: /^this-dep/ // Yet we want `this-dep` (and all its sub-paths) 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'`.
- Subpath imports are supported with regexes, meaning that `include: /^lodash/` will externalize `lodash` and also `lodash/map`, `lodash/merge`, etc.
### 2/ This plugin is not _that_ smart
It uses an exact match against your imports _as written in your code_. No resolving of path aliases or substitutions is made.
### 3/ Order matters
If you're also using [`@rollup/plugin-node-resolve`](https://github.com/rollup/plugins/tree/master/packages/node-resolve/#readme), make sure this plugin comes _before_ it in the `plugins` array:
```js
import nodeExternals from 'rollup-plugin-node-externals'
import nodeResolve from '@rollup/plugin-node-resolve'
export default {
...
plugins: [
nodeExternals(),
nodeResolve(),
]
}
```
Note that as of version 7.1, this plugin has a `enforce: 'pre'` property that will make Rollup and Vite call it very early in the module resolution process. Nevertheless, it is best 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.
### 5/ Using with Vite
This plugin has been compatible with Vite out-of-the-box since version 7.1. If you found an old tutorial on the Internet telling you to use some special trick to make it work with Vite… just don't. Here's how you should write your `vite.config.js`:
```js
import { defineConfig } from 'vite'
import nodeExternals from 'rollup-plugin-node-externals'
export default defineConfig({
...
plugins: [
nodeExternals()
// other plugins follow
]
})
```
> [!IMPORTANT]
> Make sure you use the _top-level plugins array_ in `vite.config.js` as shown above. __Using `build.rollupOptions.plugins` will probably not work__. See [#35](https://github.com/Septh/rollup-plugin-node-externals/issues/35) for details.
## What's new in v9
This version mainly enhances performance when used in watch mode. This was achieved by ensuring that the `buildStart` hook builds the full dependencies list only when necessary.
### Breaking changes
- As initiated with v7, each major update requires at least the **Active LTS** [version of NodeJS](https://github.com/nodejs/Release#release-schedule) at the time of publishing. With v9, this means NodeJS v24+ (up from v8's 20+).
See [Github releases](https://github.com/Septh/rollup-plugin-node-externals/releases) for full change log.
## License
MIT