Skip to content

Commit 6a2eb0f

Browse files
committed
Doc update
1 parent 5e9015b commit 6a2eb0f

File tree

1 file changed

+43
-12
lines changed

1 file changed

+43
-12
lines changed

README.md

Lines changed: 43 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# rollup-plugin-node-externals
2-
A Rollup plugin that automatically declares NodeJS built-in modules as `external`. Also handles npm dependencies, devDependencies, peerDependencies and optionalDependencies.
2+
A Rollup/Vite plugin that automatically declares NodeJS built-in modules as `external`. Also handles npm dependencies, devDependencies, peerDependencies and optionalDependencies.
33

44
Works in npm/yarn/pnpm/lerna monorepos too!
55

66

77
## Why you need this
8-
<details><summary>(click to expand)</summary>
8+
<details><summary>(click to read)</summary>
99

1010
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 generates an `Unresolved dependencies` warning.
1111

@@ -109,10 +109,10 @@ Set the `builtins` option to `false` if you'd like to use some shims/polyfills f
109109

110110
#### builtinsPrefix?: 'add' | 'strip' | 'ignore' = 'add'
111111
How to handle the `node:` scheme used in recent versions of Node (i.e., `import path from 'node:path'`).
112-
- If `add` (the default, recommended), the `node:` prefix is always added. In effect, this homogenizes all your imports of Node builtins to their prefixed version.
113-
- If `strip`, the prefix is always removed. In effect, this homogenizes all your imports of Node builtins to their unprefixed version.
112+
- If `add` (the default, recommended), the `node:` scheme is always added. In effect, this dedupes your imports of Node builtins by homogenizing their names to their schemed version.
113+
- If `strip`, the scheme is always removed. In effect, this dedupes your imports of Node builtins by homogenizing their names to their unschemed version. Schemed-only builtins like `node:test` are not stripped.
114114
- `ignore` will simply leave all builtins imports as written in your code.
115-
> _Note that prefix handling is always applied, regardless of the `builtins` options being enabled or not._
115+
> _Note that scheme handling is always applied, regardless of the `builtins` options being enabled or not._
116116
117117
#### packagePath?: string | string[] = []
118118
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.
@@ -148,14 +148,14 @@ nodeExternals({
148148
- Subpath imports are supported with regexes, meaning that `include: /^lodash/` will externalize `lodash` and also `lodash/map`, `lodash/merge`, etc.
149149

150150
### 2/ This plugin is not _that_ smart
151-
It uses an exact match against your imports _as written in your code_, so if your are using some kind of path substitution, eg.:
151+
It uses an exact match against your imports _as written in your code_. No resolving of path aliases or substitutions is made:
152152

153153
```js
154-
// In your code, say '@/' is mapped to some directory:
155-
import something from '@/mylib'
154+
// In your code, say '@/lib' is an alias for node_modules/deep/path/to/some/lib:
155+
import something from '@/lib'
156156
```
157157

158-
and you don't want `mylib` bundled in, then write:
158+
If you don't want `lib` bundled in, then write:
159159

160160
```js
161161
// In rollup.config.js:
@@ -180,17 +180,48 @@ export default {
180180
}
181181
```
182182

183-
As a general rule of thumb, you might want to always make this plugin the first one in the `plugins` array.
183+
As a general rule of thumb, you will want to always make this plugin the first one in the `plugins` array.
184184

185185
### 4/ Rollup rules
186186
Rollup's own `external` configuration option always takes precedence over this plugin. This is intentional.
187187

188+
### 5/ Using with Vite
189+
While this plugin has always been compatible with Vite, it was previously necessary to use the following `vite.config.js` to make it work reliably in every situations:
190+
191+
```js
192+
import { defineConfig } from 'vite'
193+
import nodeExternals from 'rollup-plugin-node-externals'
194+
195+
export default defineConfig({
196+
...
197+
plugins: [
198+
{ enforce: 'pre', ...nodeExternals() },
199+
// other plugins follow
200+
]
201+
})
202+
```
203+
204+
Since version 7.1, this is no longer necessary and you can use the normal syntax instead. You still want to keep this plugin early in the `plugins` array, though.
205+
206+
```js
207+
import { defineConfig } from 'vite'
208+
import nodeExternals from 'rollup-plugin-node-externals'
209+
210+
export default defineConfig({
211+
...
212+
plugins: [
213+
nodeExternals()
214+
// other plugins follow
215+
]
216+
})
217+
```
218+
188219

189220
## Breaking changes
190221

191222
### Breaking changes in version 7
192-
- This package now supports the latest release of [any major version that is supported by Node.js itself](https://github.com/nodejs/Release#release-schedule).
193-
- The undocumented `externals` named export has been removed.
223+
- This package now only supports the [Maintenance, LTS and Current versions](https://github.com/nodejs/Release#release-schedule) of Node.js.
224+
- The previously undocumented `externals` named export has been removed.
194225

195226
### Breaking changes in previous versions
196227
<details><summary>Previous versions -- click to expand</summary>

0 commit comments

Comments
 (0)