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
+60-45Lines changed: 60 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,119 +10,132 @@ However, this must be done for each and every NodeJS built-in that you happen to
10
10
11
11
So the primary goal of this plugin is simply to automatically declare all NodeJS built-in modules as `external`.
12
12
13
-
This plugin will also allow you to declare your dependencies (as declared in your `package.json` file) as `external`.
13
+
As an added bonus, this plugin will also allow you to declare your dependencies (as declared in your local or monorepo `package.json` file) as external.
// Can be a string or an array of strings for monorepos -- see below
33
-
packagePath:'path/to/package.json',
31
+
// The path(s) to your package.json. Optional. See below for default.
32
+
packagePath?: string|string[],
34
33
35
34
// Make node builtins external. Optional. Default: true
36
-
builtins:true,
35
+
builtins?: boolean,
36
+
37
+
// Treat prefixed builtins as their unprefixed counterpart. Optional. Default: true
38
+
prefixedBuiltins?: boolean|'strip',
37
39
38
40
// Make pkg.dependencies external. Optional. Default: false
39
-
deps:false,
41
+
deps?: boolean,
42
+
43
+
// Make pkg.devDependencies external. Optional. Default: true
44
+
devDeps?: boolean,
40
45
41
46
// Make pkg.peerDependencies external. Optional. Default: true
42
-
peerDeps:true,
47
+
peerDeps?: boolean,
43
48
44
49
// Make pkg.optionalDependencies external. Optional. Default: true
45
-
optDeps:true,
46
-
47
-
// Make pkg.devDependencies external. Optional. Default: true
48
-
devDeps:true,
50
+
optDeps?: boolean,
49
51
50
-
// Modules to exclude from externals. Optional. Default: []
51
-
exclude:[],
52
+
// Modules to force include in externals. Optional. Default: []
53
+
include?: string|RegExp| (string|RegExp)[],
52
54
53
-
// Modules to include in externals. Optional. Default: []
54
-
include:[]
55
+
// Modules to force exclude from externals. Optional. Default: []
56
+
exclude?: string|RegExp| (string|RegExp)[]
55
57
})
56
58
]
57
59
}
58
60
```
59
61
60
62
Most of the time, the built-in defaults are just what you need:
61
-
```js
63
+
```typescript
62
64
importexternalsfrom'rollup-plugin-node-externals'
63
65
64
66
exportdefault {
65
-
//...
67
+
...
66
68
plugins: [
67
69
externals(), // Bundle deps in; make all Node builtins, devDeps, peerDeps and optDeps external
68
70
]
69
71
}
70
72
```
71
73
72
74
### Options
73
-
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.
75
+
By default, this 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.
74
76
75
77
#### packagePath?: string | string[] = []
76
78
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.
77
79
78
80
#### builtins?: boolean = true
81
+
Set the `builtins` option to `false` if you'd like to use some shims for those.
82
+
83
+
#### prefixedBuiltins?: boolean | 'strip' = true
84
+
How to handle the `node:` (or sometimes `nodejs:`) prefix some authors use in their code (i.e., `import path from 'node:path'`). If `true` (default), prefixed builtins are treated as their unprefixed equivalent. If `strip`, the prefix is removed from the name and other plugins will never know it was there.
85
+
79
86
#### deps?: boolean = false
80
-
#### devDeps?: boolean = true
87
+
Set the `deps` option to `true` to externalize your normal dependencies, therefore preventing Rollup from bundling them with your code.
88
+
89
+
#### devDeps?: boolean = true,
81
90
#### peerDeps?: boolean = true
82
91
#### optDeps?: boolean = true
83
-
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.
92
+
Set the `devDeps`, `peerDeps` and `optDeps` options to `false` to prevent the corresponding dependencies from being externalized, therefore letting Rollup bundle them with your code. Note that bundling these dependencies is quite meaningless but it might be useful as a transitional step before migrating them to `devDependencies`.
Use the `include` option to force certain dependencies into the list of externals, for example:
88
-
```js
96
+
Use the `include` option to force certain dependencies into the list of externals:
97
+
```typescript
89
98
externals({
90
99
deps: false, // Bundle dependencies in
91
100
include:/^fsevents/// Except for fsevents
92
101
})
93
102
```
94
103
95
-
Use the `exclude` option to remove certain dependencies from the list of externals, for example:
96
-
```js
104
+
Conversely, use the `exclude` option to remove certain dependencies from the list of externals:
105
+
```typescript
97
106
externals({
98
107
deps: true, // Don't bundle dependencies, we'll import/require them at runtime instead
99
108
exclude: [
100
-
'electron-reload', // Yet we want `electron-reload` bundled in
101
-
/^vue/// as well as the VueJS family (vue, vuex, vue-router, etc.)
109
+
'electron-reload'// Yet we want `electron-reload` bundled in
102
110
]
103
111
})
104
112
```
105
113
106
-
> 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/`.
114
+
## Notes
115
+
### 1/ This plugin is smart
116
+
Falsy values in `include` and `exclude` are silently ignored. This allows for conditional constructs like so: `exclude: process.env.NODE_ENV === 'production' && /my-prod-only-dep/`.
107
117
108
-
> Note2 : this plugin uses an exact match against your imports, so if your are using some path substitution in your code, eg.:
109
-
```js
110
-
// in your code, say '@/' is mapped to some directory:
118
+
### 2/ This plugin is not _that_ smart
119
+
It uses an exact match against your imports, so if your are using some path substitution in your code, eg.:
120
+
```typescript
121
+
// In your code, say '@/' is mapped to some directory:
111
122
importsomethingfrom'@/mylib'
112
123
```
113
-
> and you don't want `mylib` bundled in, then write:
124
+
and you don't want `mylib` bundled in, then write:
114
125
```js
115
-
//in rollup.config.js:
126
+
//In rollup.config.js:
116
127
externals({
117
128
include:'@/mylib'
118
129
})
119
130
```
120
131
121
-
> Note3: if you're also using `@rollup/plugin-node-resolve`, make sure this plugin comes before it in the `plugins` array:
122
-
```js
132
+
### 3/ Order matters
133
+
If you're also using `@rollup/plugin-node-resolve`, make sure this plugin comes _before_ it in the `plugins` array:
134
+
```typescript
123
135
importexternalsfrom'rollup-plugin-node-externals'
124
136
importresolvefrom'@rollup/plugin-node-resolve'
125
-
// ...
137
+
138
+
...
126
139
127
140
exportdefault {
128
141
// ...
@@ -134,20 +147,22 @@ export default {
134
147
}
135
148
```
136
149
150
+
### 4/ Rollup rules
151
+
Rollup's own `external` configuration option always takes precedence over this plugin. This is intentional.
137
152
138
-
### Migrating from version 1.x
139
-
- In 1.x, normal dependencies were externalized by default. This is no more true, so you'll need to change:
140
-
```js
153
+
154
+
## Migrating from version 1.x
155
+
- In 1.x, normal dependencies were externalized by default. This is no more true since 2.0, so you'll need to change:
156
+
```typescript
141
157
externals()
142
158
```
143
159
to:
144
-
```js
160
+
```typescript
145
161
externals({ deps: true })
146
162
```
147
163
if you want the same behavior.
148
164
149
-
150
-
- For consistency with all other Rollup plugins out there, the `except` option from 1.x has been deprecated in 2.0 and removed in 3.0. Use the Rollup-friendly `exclude` option instead.
165
+
- The `except` option from 1.x has been deprecated in 2.0 and removed in 3.0. Use the Rollup-friendlier `exclude` option instead.
0 commit comments