You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+43-31Lines changed: 43 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,15 @@
1
1
# rollup-plugin-node-externals
2
2
3
-
A Rollup plugin that automatically declares NodeJS built-in modules as `external`. Can also handle npm dependencies, devDependencies, peerDependencies and optionalDependencies.
3
+
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!
4
4
5
5
## Why?
6
6
7
-
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, depending on what you're building:
8
-
*If building a *standalone app*, e.g. for the browser, you'll need to use some kind of shim like those provided by [rollup-plugin-node-builtins](https://github.com/calvinmetcalf/rollup-plugin-node-builtins).
9
-
*If building *an npm module or lib*, you'll need to tell Rollup that the `path` module is in fact `external`: this way, Rollup won't try to bundle the module in and rather leave the `import` statement as is (or translate it to a `require()` call if bundling for CommonJS).
7
+
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:
8
+
*Either use some kind of shim like those provided by [rollup-plugin-node-builtins](https://github.com/calvinmetcalf/rollup-plugin-node-builtins).
9
+
*Or 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).
10
10
11
11
However, this must be done for each and every NodeJS built-in: `path`, `os`, `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 `external`.
12
+
> Note: the list of builtins is obtained via [the builtin-modules package](https://github.com/sindresorhus/builtin-modules) by Sindre Sorhus and should be up-to-date with your current NodeJS version.
12
13
13
14
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](https://electronjs.org) app, for example.
// The path to your package.json. Optional. Default: process.cwd() which is usally the same dir where rollup.config.js stands
34
+
// The path(s) to your package.json. Optional.
35
+
// Can be a string or an array of strings for monorepos -- see below
33
36
packagePath:'path/to/package.json',
34
37
35
-
// Make node built-ins external. Optional. Default: true
38
+
// Make node builtins external. Optional. Default: true
36
39
builtins:true,
37
40
38
41
// Make pkg.dependencies external. Optional. Default: false
@@ -63,22 +66,19 @@ export default {
63
66
Most of the time, the built-in defaults are just what you need:
64
67
```js
65
68
importexternalsfrom'rollup-plugin-node-externals'
66
-
// ...
67
69
68
70
exportdefault {
69
71
// ...
70
72
plugins: [
71
-
externals(), // Bundle deps in; make Node built-ins, devDeps, peerDeps and optDeps external
73
+
externals(), // Bundle deps in; make all Node builtins, devDeps, peerDeps and optDeps external
72
74
]
73
75
}
74
76
```
75
77
76
-
> Note: the list of builtins is obtained via [the builtin-modules package](https://github.com/sindresorhus/builtin-modules), by Sindre Sorhus and should be up-to-date with your current NodeJS version.
77
-
78
-
> Note: if you're also using `rollup-plugin-node-resolve`, make sure this plugin comes before it in the `plugins` array:
78
+
> Note: if you're also using `@rollup/plugin-node-resolve`, make sure this plugin comes before it in the `plugins` array:
79
79
```js
80
80
importexternalsfrom'rollup-plugin-node-externals'
81
-
importresolvefrom'rollup-plugin-node-resolve'
81
+
importresolvefrom'@rollup/plugin-node-resolve'
82
82
// ...
83
83
84
84
exportdefault {
@@ -94,43 +94,54 @@ export default {
94
94
95
95
### Options
96
96
97
-
By default, the plugin will mark all Node built-in modules and _all_ your `dev-`, `peer-` and `optionalDependencies` as external. Normal `dependencies` are left unmarked so Rollup will still bundle them with your code as expected in most situations.
97
+
By default, the plugin will mark all Node builtin modules and _all_ your `dev-`, `peer-` and `optionalDependencies` as external. Normal `dependencies` are left unmarked so Rollup will still bundle them with your code as expected in most situations.
98
+
99
+
-**packagePath?: string | string[] = []**
100
+
101
+
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.
98
102
99
-
- Set the `deps`, `devDeps`, `peerDeps` and/or `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.
103
+
-**builtins?: boolean = true**
104
+
-**deps?: boolean = false**
105
+
-**devDeps?: boolean = true**
106
+
-**peerDeps?: boolean = true**
107
+
-**optDeps?: boolean = true**
100
108
101
-
- Use the `exclude` option to remove certain dependencies from the list of externals. `exclude` can be a string, a regex, or an array of those, for example:
109
+
Set the `builtins`, `deps`, `devDeps`, `peerDeps` and/or `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.
Use the `exclude` option to remove certain dependencies from the list of externals, for example:
102
115
```js
103
116
externals({
104
-
deps:true,// Don't bundle dependencies, we'll require() them at runtime instead
105
-
exclude: [
106
-
'electron-reload', // Yet we want `electron-reload` bundled in
107
-
/^vuex?/// as well as the VueJS family (vue, vuex, vue-router, etc.)
108
-
]
117
+
deps:true, // Don't bundle dependencies, we'll require() them at runtime instead
118
+
exclude: [
119
+
'electron-reload', // Yet we want `electron-reload` bundled in
120
+
/^vuex?/// as well as the VueJS family (vue, vuex, vue-router, etc.)
121
+
]
109
122
})
110
123
```
111
124
112
-
-Use the `include` option to force certain dependencies into the list of externals, for example:
125
+
Use the `include` option to force certain dependencies into the list of externals, for example:
113
126
```js
114
127
externals({
115
-
peerDeps:false, // Bundle peerDependencies in
116
-
include:/^lodash/// Except for Lodash
128
+
peerDeps:false, // Bundle peerDependencies in
129
+
include:/^lodash/// Except for Lodash
117
130
})
118
131
```
119
-
Just like `exclude`, the `include` option can be a string, a regex or an array of those.
120
132
121
133
> Note 1 : falsy values in `include` and `exclude` are silently ignored. This allows for conditional constructs like so: `exclude: process.env.NODE_ENV === 'production' && /mydep/`.
122
134
123
135
> Note2 : this plugin uses an exact match against your imports, so if your are using some path substitution in your code, eg.:
124
136
```js
125
-
// in your code:
126
-
importsomethingfrom'@/mylib'// Say '@/' is mapped to some directory
127
-
...
137
+
// in your code, say '@/' is mapped to some directory:
138
+
importsomethingfrom'@/mylib'
128
139
```
129
140
and you don't want `mylib` bundled in, then write:
130
141
```js
131
142
// in rollup.config.js:
132
143
externals({
133
-
include:'@/mylib'// /^@\// or /mylib$/ would work too
144
+
include:'@/mylib'
134
145
})
135
146
```
136
147
@@ -145,8 +156,9 @@ to:
145
156
externals({ deps:true })
146
157
```
147
158
if you want the same behavior.
148
-
- For consistency with all other Rollup plugins out there, the `except` option from 1.x is now deprecated in favor of the Rollup-friendly `exclude` option.
149
-
`except` is still accepted for backward compatibility and works exactly the same as `exclude` but it will issue a warning if used. To suppress this warning, just replace `except` with `exclude`.
159
+
160
+
161
+
- For consistency with all other Rollup plugins out there, the `except` option from 1.x is now deprecated in favor of the Rollup-friendly `exclude` option. It will be removed in the next major release but is still accepted for backward compatibility and works exactly the same as `exclude` but it will issue a warning if used. To suppress this warning, just replace `except` with `exclude`.
0 commit comments