Skip to content

Commit 5d3d043

Browse files
feat: add externalsPresets.nodeModules preset (#21569)
* feat: add externalsPresets.nodeModules preset Externalize installed packages (requests resolving into a node_modules directory) instead of bundling them, loading them via require()/import at runtime. Opt-in only; relative/absolute and CSS/url requests are never treated as package externals. Useful for server-side rendering builds. * fix: keep package CSS/asset imports bundled under nodeModules preset Only externalize a request that resolves to a runtime-loadable JS/JSON file, so a package's stylesheet or asset imported from JS stays bundled for webpack to process instead of being require()'d/import-ed at runtime. Also refresh the ecmaVersion browserslist inline snapshots for the new externalsPresets.nodeModules key. * feat: add allowlist option to the nodeModules externals preset Extend externalsPresets.nodeModules to accept `true | { allowlist }`, where allowlist items are an exact request string, a RegExp, or a (request) => boolean filter. Matching requests stay bundled while the rest are externalized, matching webpack-node-externals' allowlist so the preset is a drop-in built-in replacement. * docs(changeset): recommend the nodeModules preset over webpack-node-externals Point users at the built-in preset as the replacement for the webpack-node-externals plugin, and add the ordering prefix the changeset naming convention requires. * fix: keep `#` subpath imports bundled under the nodeModules preset A `#` specifier only resolves against the importing package's own `imports` field, so it can never be emitted as an external request. A bundled package's `#internal` import resolved into node_modules and was externalized, making node throw MODULE_NOT_FOUND at runtime. * docs(changeset): tighten the nodeModules preset entry to one sentence * fix: keep aliased packages bundled under the nodeModules preset The external keeps the original request, so a `resolve.alias` remapping a bare request to a different package was externalized under its original name and loaded the unaliased package at runtime. Externalize only when the request resolves into the package it names. * chore: reword a comment cspell rejects
1 parent 2d18aa6 commit 5d3d043

40 files changed

Lines changed: 391 additions & 2 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"webpack": minor
3+
---
4+
5+
Add the `externalsPresets.nodeModules` preset with an `allowlist` option to externalize installed packages, replacing the `webpack-node-externals` plugin.

‎declarations/WebpackOptions.d.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1722,6 +1722,17 @@ export interface ExternalsPresets {
17221722
* Treat node.js built-in modules like fs, path or vm as external and load them via require() when used.
17231723
*/
17241724
node?: boolean;
1725+
/**
1726+
* Treat installed packages (requests resolving into a 'node_modules' directory) as external and load them via require()/import at runtime instead of bundling them (useful for server-side rendering builds).
1727+
*/
1728+
nodeModules?:
1729+
| boolean
1730+
| {
1731+
/**
1732+
* Keep these requests bundled instead of externalizing them.
1733+
*/
1734+
allowlist?: (RegExp | string | ((request: string) => boolean))[];
1735+
};
17251736
/**
17261737
* Treat NW.js legacy nw.gui module as external and load it via require() when used.
17271738
*/

‎lib/WebpackOptionsApply.js‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,91 @@ class WebpackOptionsApply extends OptionsApply {
149149
).apply(compiler);
150150
}
151151
}
152+
if (options.externalsPresets.nodeModules) {
153+
// @ts-expect-error https://github.com/microsoft/TypeScript/issues/41697
154+
const ExternalsPlugin = require("./ExternalsPlugin");
155+
156+
const type = options.output.module ? "module-import" : "node-commonjs";
157+
const preset = options.externalsPresets.nodeModules;
158+
const allowlist = preset === true ? undefined : preset.allowlist;
159+
/**
160+
* @param {string} request the request
161+
* @returns {boolean} true when the request should stay bundled
162+
*/
163+
const isAllowed = (request) =>
164+
allowlist !== undefined &&
165+
allowlist.some((entry) =>
166+
entry instanceof RegExp
167+
? entry.test(request)
168+
: typeof entry === "function"
169+
? entry(request)
170+
: entry === request
171+
);
172+
// Relative/absolute requests are never installed packages, and `#` subpath
173+
// imports only resolve against the importing package's own `imports` field.
174+
const NEVER_EXTERNAL = /^(?:\.\.?(?:\/|$)|\/|[A-Za-z]:[\\/]|#)/;
175+
const NODE_MODULES = /[\\/]node_modules[\\/]/i;
176+
// Only JS-loadable resolutions are externalized; a package's CSS/asset
177+
// imported from JS must stay bundled so webpack can process it.
178+
const RUNTIME_LOADABLE = /\.(?:m|c)?js$|\.json$|\.node$/i;
179+
/**
180+
* @param {string} request a request or a path below a `node_modules` directory
181+
* @returns {string} the package name it belongs to
182+
*/
183+
const getPackageName = (request) => {
184+
const parts = request.split("/");
185+
return request.startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0];
186+
};
187+
// `url()`/CSS `@import` references are handled by their own presets.
188+
const NON_JS_DEPENDENCY_TYPES = new Set([
189+
"url",
190+
"css-import",
191+
"css-import-local-module",
192+
"css-import-global-module"
193+
]);
194+
195+
new ExternalsPlugin(
196+
// Keep `require()` semantics for CommonJS deps even with module output.
197+
(dependency) =>
198+
dependency.category === "commonjs" ? "node-commonjs" : type,
199+
({ request, context, dependencyType, getResolve }, callback) => {
200+
if (
201+
NEVER_EXTERNAL.test(request) ||
202+
NON_JS_DEPENDENCY_TYPES.has(dependencyType) ||
203+
isAllowed(request)
204+
) {
205+
return callback();
206+
}
207+
208+
const resolve =
209+
/** @type {(context: string, request: string, callback: (err?: Error | null, result?: string | false) => void) => void} */
210+
(getResolve());
211+
212+
// Externalize the package only when it resolves to a runtime-loadable
213+
// file inside a node_modules directory.
214+
resolve(context, request, (err, result) => {
215+
if (
216+
err ||
217+
!result ||
218+
!NODE_MODULES.test(result) ||
219+
!RUNTIME_LOADABLE.test(result)
220+
) {
221+
return callback();
222+
}
223+
// The external keeps the original request, so requests that
224+
// `resolve.alias` sends to another package must stay bundled.
225+
const resolvedPath = result.split(NODE_MODULES).pop();
226+
const resolvedPackageName = getPackageName(
227+
/** @type {string} */ (resolvedPath).replace(/\\/g, "/")
228+
);
229+
callback(
230+
null,
231+
resolvedPackageName === getPackageName(request) ? true : undefined
232+
);
233+
});
234+
}
235+
).apply(compiler);
236+
}
152237
if (options.externalsPresets.deno) {
153238
const DenoTargetPlugin = require("./deno/DenoTargetPlugin");
154239

‎lib/config/defaults.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2196,6 +2196,8 @@ const applyExternalsPresetsDefaults = (
21962196
isUniversal("node"))
21972197
)
21982198
);
2199+
// Opt-in only: never auto-externalize installed packages, it would change existing builds.
2200+
D(externalsPresets, "nodeModules", false);
21992201
D(
22002202
externalsPresets,
22012203
"deno",

‎schemas/WebpackOptions.check.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎schemas/WebpackOptions.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1676,6 +1676,45 @@
16761676
"description": "Treat node.js built-in modules like fs, path or vm as external and load them via require() when used.",
16771677
"type": "boolean"
16781678
},
1679+
"nodeModules": {
1680+
"description": "Treat installed packages (requests resolving into a 'node_modules' directory) as external and load them via require()/import at runtime instead of bundling them (useful for server-side rendering builds).",
1681+
"anyOf": [
1682+
{
1683+
"description": "Enable or disable externalizing installed packages.",
1684+
"type": "boolean"
1685+
},
1686+
{
1687+
"description": "Externalize installed packages with options.",
1688+
"type": "object",
1689+
"additionalProperties": false,
1690+
"properties": {
1691+
"allowlist": {
1692+
"description": "Keep these requests bundled instead of externalizing them.",
1693+
"type": "array",
1694+
"items": {
1695+
"description": "A request that should stay bundled.",
1696+
"anyOf": [
1697+
{
1698+
"description": "Requests matching the RegExp stay bundled.",
1699+
"instanceof": "RegExp",
1700+
"tsType": "RegExp"
1701+
},
1702+
{
1703+
"description": "An exact request that should stay bundled.",
1704+
"type": "string"
1705+
},
1706+
{
1707+
"description": "A function returning true for requests that should stay bundled.",
1708+
"instanceof": "Function",
1709+
"tsType": "((request: string) => boolean)"
1710+
}
1711+
]
1712+
}
1713+
}
1714+
}
1715+
}
1716+
]
1717+
},
16791718
"nwjs": {
16801719
"description": "Treat NW.js legacy nw.gui module as external and load it via require() when used.",
16811720
"type": "boolean"

‎test/Defaults.unittest.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ describe("snapshots", () => {
159159
"electronPreload": false,
160160
"electronRenderer": false,
161161
"node": false,
162+
"nodeModules": false,
162163
"nwjs": false,
163164
"web": true,
164165
},
@@ -3224,12 +3225,13 @@ describe("snapshots", () => {
32243225
- "electronPreload": false,
32253226
- "electronRenderer": false,
32263227
- "node": false,
3227-
- "nwjs": false,
32283228
+ "electron": true,
32293229
+ "electronMain": null,
32303230
+ "electronPreload": null,
32313231
+ "electronRenderer": null,
32323232
+ "node": true,
3233+
@@ ... @@
3234+
- "nwjs": false,
32333235
+ "nwjs": true,
32343236
@@ ... @@
32353237
- "externalsType": "var",

‎test/__snapshots__/Cli.basictest.js.snap‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1250,6 +1250,51 @@ Object {
12501250
"multiple": false,
12511251
"simpleType": "boolean",
12521252
},
1253+
"externals-presets-node-modules": Object {
1254+
"configs": Array [
1255+
Object {
1256+
"description": "Enable or disable externalizing installed packages.",
1257+
"multiple": false,
1258+
"path": "externalsPresets.nodeModules",
1259+
"type": "boolean",
1260+
},
1261+
],
1262+
"description": "Enable or disable externalizing installed packages.",
1263+
"multiple": false,
1264+
"simpleType": "boolean",
1265+
},
1266+
"externals-presets-node-modules-allowlist": Object {
1267+
"configs": Array [
1268+
Object {
1269+
"description": "Requests matching the RegExp stay bundled.",
1270+
"multiple": true,
1271+
"path": "externalsPresets.nodeModules.allowlist[]",
1272+
"type": "RegExp",
1273+
},
1274+
Object {
1275+
"description": "An exact request that should stay bundled.",
1276+
"multiple": true,
1277+
"path": "externalsPresets.nodeModules.allowlist[]",
1278+
"type": "string",
1279+
},
1280+
],
1281+
"description": "Requests matching the RegExp stay bundled. An exact request that should stay bundled.",
1282+
"multiple": true,
1283+
"simpleType": "string",
1284+
},
1285+
"externals-presets-node-modules-allowlist-reset": Object {
1286+
"configs": Array [
1287+
Object {
1288+
"description": "Clear all items provided in 'externalsPresets.nodeModules.allowlist' configuration. Keep these requests bundled instead of externalizing them.",
1289+
"multiple": false,
1290+
"path": "externalsPresets.nodeModules.allowlist",
1291+
"type": "reset",
1292+
},
1293+
],
1294+
"description": "Clear all items provided in 'externalsPresets.nodeModules.allowlist' configuration. Keep these requests bundled instead of externalizing them.",
1295+
"multiple": false,
1296+
"simpleType": "boolean",
1297+
},
12531298
"externals-presets-nwjs": Object {
12541299
"configs": Array [
12551300
Object {

‎test/configCases/ecmaVersion/browserslist-config-env-extends/webpack.config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ module.exports = {
4545
"electronPreload": false,
4646
"electronRenderer": false,
4747
"node": false,
48+
"nodeModules": false,
4849
"nwjs": false,
4950
"web": true,
5051
}

‎test/configCases/ecmaVersion/browserslist-config-env/webpack.config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ module.exports = {
4545
"electronPreload": false,
4646
"electronRenderer": false,
4747
"node": false,
48+
"nodeModules": false,
4849
"nwjs": false,
4950
"web": true,
5051
}

0 commit comments

Comments
 (0)