Skip to content

Commit 171b2b6

Browse files
committed
Update README.md with #35 warning
1 parent 04add45 commit 171b2b6

File tree

1 file changed

+14
-11
lines changed

1 file changed

+14
-11
lines changed

README.md

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

14-
Works in npm/yarn/pnpm/lerna monorepos too!
14+
Works in pnpm/yarn/lerna monorepos too!
1515

1616

1717
## Why you need this
1818
<details><summary>(click to read)</summary>
1919

20-
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.
20+
By default, Rollup doesn't know a thing about NodeJS, so trying to bundle simple things like `import path from 'path'` in your code results in a `Unresolved dependencies` warning.
2121

22-
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).
22+
The solution here is quite simple: you must tell Rollup that the `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).
2323

24-
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.
24+
However, this must be done for each and every NodeJS built-in you happen to use in your program: `path`, `os`, `fs`, `url`, etc., which can quickly become cumbersome when done manually.
2525

2626
So the primary goal of this plugin is simply to automatically declare all NodeJS built-in modules as external.
2727

28-
As an added bonus, this plugin will also allow you to declare your dependencies (as per your local or monorepo `package.json` file(s)) as external.
28+
As an added bonus, this plugin will also declare your dependencies (as per your local or monorepo `package.json` file(s)) as external.
2929
</details>
3030

3131
## Requirements
@@ -123,8 +123,8 @@ Set the `builtins` option to `false` if you'd like to use some shims/polyfills f
123123

124124
#### builtinsPrefix?: 'add' | 'strip' | 'ignore' = 'add'
125125
How to handle the `node:` scheme used in recent versions of Node (i.e., `import path from 'node:path'`).
126-
- 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.
127-
- 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.
126+
- If `add` (the default, recommended), the `node:` scheme is always added if missing. In effect, this dedupes your imports of Node builtins by homogenizing their names to their schemed version.
127+
- 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 never stripped.
128128
- `ignore` will simply leave all builtins imports as written in your code.
129129
> _Note that scheme handling is always applied, regardless of the `builtins` options being enabled or not._
130130
@@ -165,11 +165,11 @@ nodeExternals({
165165
It uses an exact match against your imports _as written in your code_. No resolving of path aliases or substitutions is made:
166166

167167
```js
168-
// In your code, say '@/lib' is an alias for source/deep/path/to/some/lib:
168+
// In your code, say '@/lib' is an alias for node_modules/lib/deep/path/to/some/file.js:
169169
import something from '@/lib'
170170
```
171171

172-
If you don't want `lib` bundled in, then write:
172+
If you don't want `node_modules/lib/deep/path/to/some/file.js` bundled in, then write:
173173

174174
```js
175175
// In rollup.config.js:
@@ -194,7 +194,7 @@ export default {
194194
}
195195
```
196196

197-
Note that as of version 7, this plugin's `resolveId` hook has a `order: 'pre'` property that will make Rollup 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.
197+
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.
198198

199199
### 4/ Rollup rules
200200
Rollup's own `external` configuration option always takes precedence over this plugin. This is intentional.
@@ -230,12 +230,15 @@ export default defineConfig({
230230
})
231231
```
232232

233+
> [!NOTE]
234+
> 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.
235+
233236

234237
## Breaking changes
235238

236239
### Breaking changes in version 8
237240
- Removed support for Rollup 3.
238-
- Removed `order: pre` from resolveId hook (see #33). Might force users who relied on this, to make sure this plugin comes first in the plugins array.
241+
- Removed `order: pre` from `resolveId` hook (see [#33](https://github.com/Septh/rollup-plugin-node-externals/issues/33)). Might force users who relied on this, to make sure this plugin comes first in the plugins array.
239242

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

0 commit comments

Comments
 (0)