Skip to content

Commit 5798eda

Browse files
feat: add interop hint for object externals (#21371)
A non-ESM external (amd/umd/commonjs/...) is a dynamic module, so importing its default from a strict ES module (package "type": "module") yields the whole exports object instead of the unboxed default, while a non-strict importer unboxes it. This importer-dependent behavior matches Node.js and esbuild but leaves no way to pin the interop for a specific external. Add an `interop` hint on the object form of an external, mirroring Rollup's `output.interop`: - "esModule": treat the external as an ES module namespace, so `default` unboxes to `.default` regardless of the importer's strictness. - "default": treat the external as CommonJS, so `default` is the whole exports (Node.js semantics). Closes #20383
1 parent 243396c commit 5798eda

11 files changed

Lines changed: 402 additions & 18 deletions

File tree

‎.changeset/external-interop.md‎

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 `interop` ("default" | "esModule") hint for object externals to control default-export interop, matching Rollup's `output.interop`.

‎declarations/WebpackOptions.d.ts‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -878,16 +878,18 @@ export type EntryDynamicNormalized =
878878
* The entry point(s) of the compilation.
879879
*/
880880
export type EntryNormalized = EntryDynamicNormalized | EntryStaticNormalized;
881+
/**
882+
* How an external's exports interoperate with ES module imports, independent of the importing module's strictness (similar to Rollup's `output.interop`). 'default': treat as CommonJS, the default import is the whole exports (Node.js semantics). 'esModule': treat as an ES module namespace, the default import is unboxed to `.default`.
883+
*/
884+
export type ExternalItemInterop = "default" | "esModule";
881885
/**
882886
* The dependency used for the external.
883887
*/
884888
export type ExternalItemValue =
885889
| string[]
886890
| boolean
887891
| string
888-
| {
889-
[k: string]: any;
890-
};
892+
| (ExternalItemValueObjectKnown & ExternalItemValueObjectUnknown);
891893
/**
892894
* Ignore specific warnings.
893895
*/
@@ -4421,6 +4423,24 @@ export interface ExternalItemObjectKnown {
44214423
export interface ExternalItemObjectUnknown {
44224424
[k: string]: ExternalItemValue;
44234425
}
4426+
/**
4427+
* The target of the external with a type, optionally with an 'interop' hint describing how its exports interoperate with ES module imports.
4428+
*/
4429+
export interface ExternalItemValueObjectKnown {
4430+
/**
4431+
* How an external's exports interoperate with ES module imports, independent of the importing module's strictness (similar to Rollup's `output.interop`). 'default': treat as CommonJS, the default import is the whole exports (Node.js semantics). 'esModule': treat as an ES module namespace, the default import is unboxed to `.default`.
4432+
*/
4433+
interop?: ExternalItemInterop;
4434+
}
4435+
/**
4436+
* The target of the external with a type, optionally with an 'interop' hint describing how its exports interoperate with ES module imports.
4437+
*/
4438+
export interface ExternalItemValueObjectUnknown {
4439+
/**
4440+
* The target of the external for a specific external type.
4441+
*/
4442+
[k: string]: string[] | string;
4443+
}
44244444
/**
44254445
* Specify options for each generator.
44264446
*/

‎lib/ExternalModule.js‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -68,8 +68,9 @@ const { register } = require("./util/serialization");
6868
/** @typedef {import("./javascript/JavascriptModulesPlugin").ChunkRenderContext} ChunkRenderContext */
6969
/** @typedef {import("./javascript/JavascriptParser").ImportAttributes} ImportAttributes */
7070
/** @typedef {import("./dependencies/ImportPhase").ImportPhaseType} ImportPhaseType */
71-
/** @typedef {import("./serialization/ObjectMiddleware").ObjectDeserializerContext<[ExternalModuleRequest, ExternalsType, string, DependencyMeta | undefined]>} ObjectDeserializerContext */
72-
/** @typedef {import("./serialization/ObjectMiddleware").ObjectSerializerContext<[ExternalModuleRequest, ExternalsType, string, DependencyMeta | undefined]>} ObjectSerializerContext */
71+
/** @typedef {import("../declarations/WebpackOptions").ExternalItemInterop} ExternalInterop */
72+
/** @typedef {import("./serialization/ObjectMiddleware").ObjectDeserializerContext<[ExternalModuleRequest, ExternalsType, string, DependencyMeta | undefined, ExternalInterop | undefined]>} ObjectDeserializerContext */
73+
/** @typedef {import("./serialization/ObjectMiddleware").ObjectSerializerContext<[ExternalModuleRequest, ExternalsType, string, DependencyMeta | undefined, ExternalInterop | undefined]>} ObjectSerializerContext */
7374
/** @typedef {import("./util/Hash")} Hash */
7475
/** @typedef {import("./util/fs").InputFileSystem} InputFileSystem */
7576
/** @typedef {import("./util/runtime").RuntimeSpec} RuntimeSpec */
@@ -829,8 +830,9 @@ class ExternalModule extends Module {
829830
* @param {ExternalsType} type type
830831
* @param {string} userRequest user request
831832
* @param {DependencyMeta=} dependencyMeta dependency meta
833+
* @param {ExternalInterop=} interop how the external's exports interoperate with ES module imports
832834
*/
833-
constructor(request, type, userRequest, dependencyMeta) {
835+
constructor(request, type, userRequest, dependencyMeta, interop) {
834836
super(JAVASCRIPT_MODULE_TYPE_DYNAMIC, null);
835837

836838
// Redeclared with the external module specific shape
@@ -846,6 +848,8 @@ class ExternalModule extends Module {
846848
this.userRequest = userRequest;
847849
/** @type {DependencyMeta=} */
848850
this.dependencyMeta = dependencyMeta;
851+
/** @type {ExternalInterop | undefined} interop shape of the external's exports (undefined = importer-driven default) */
852+
this.interop = interop;
849853
}
850854

851855
/**
@@ -917,6 +921,7 @@ class ExternalModule extends Module {
917921
id += `|attributes=${JSON.stringify(meta.attributes)}`;
918922
}
919923
}
924+
if (this.interop) id += `|interop=${this.interop}`;
920925
return id;
921926
}
922927

@@ -1050,6 +1055,20 @@ class ExternalModule extends Module {
10501055
}
10511056
break;
10521057
}
1058+
// Opt-in override for how the external's exports interoperate with ESM
1059+
// imports, independent of the importer's strictness (see Rollup's
1060+
// `output.interop`). Only meaningful for a single-request external.
1061+
if (this.interop && (!Array.isArray(request) || request.length === 1)) {
1062+
if (this.interop === "esModule") {
1063+
// external already is an ES module namespace: `default` unboxes to `.default`
1064+
this.buildMeta.exportsType = "namespace";
1065+
} else {
1066+
// "default": treat as CommonJS, `default` is the whole exports (Node.js semantics)
1067+
this.buildMeta.exportsType = "default";
1068+
this.buildMeta.defaultObject = "redirect";
1069+
}
1070+
canMangle = false;
1071+
}
10531072
this.addDependency(new StaticExportsDependency(true, canMangle));
10541073
callback();
10551074
}
@@ -1427,6 +1446,7 @@ class ExternalModule extends Module {
14271446
hash.update(`|attributes=${JSON.stringify(meta.attributes)}`);
14281447
}
14291448
}
1449+
if (this.interop) hash.update(`|interop=${this.interop}`);
14301450
super.updateHash(hash, context);
14311451
}
14321452

@@ -1439,7 +1459,8 @@ class ExternalModule extends Module {
14391459
.write(this.request)
14401460
.write(this.externalType)
14411461
.write(this.userRequest)
1442-
.write(this.dependencyMeta);
1462+
.write(this.dependencyMeta)
1463+
.write(this.interop);
14431464

14441465
super.serialize(context);
14451466
}
@@ -1456,8 +1477,10 @@ class ExternalModule extends Module {
14561477
this.userRequest = c2.read();
14571478
const c3 = c2.rest;
14581479
this.dependencyMeta = c3.read();
1480+
const c4 = c3.rest;
1481+
this.interop = c4.read();
14591482

1460-
super.deserialize(c3.rest);
1483+
super.deserialize(c4.rest);
14611484
}
14621485
}
14631486

‎lib/ExternalModuleFactoryPlugin.js‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ const { cachedSetProperty, resolveByProperty } = require("./util/cleverMerge");
2323
/** @typedef {import("../declarations/WebpackOptions").ExternalItemValue} ExternalItemValue */
2424
/** @typedef {import("../declarations/WebpackOptions").ExternalItemObjectKnown} ExternalItemObjectKnown */
2525
/** @typedef {import("../declarations/WebpackOptions").ExternalItemObjectUnknown} ExternalItemObjectUnknown */
26+
/** @typedef {import("../declarations/WebpackOptions").ExternalItemInterop} ExternalItemInterop */
2627
/** @typedef {import("../declarations/WebpackOptions").Externals} Externals */
2728
/** @typedef {import("./Dependency")} Dependency */
2829
/** @typedef {import("./ExternalModule").DependencyMeta} DependencyMeta */
@@ -161,6 +162,23 @@ class ExternalModuleFactoryPlugin {
161162
}
162163
/** @type {ExternalValue} */
163164
let externalConfig = value === true ? dependency.request : value;
165+
// `interop` is a reserved key on the object form, not a target;
166+
// pull it out so the rest stays a pure externalsType->request map.
167+
/** @type {ExternalItemInterop | undefined} */
168+
let interop;
169+
if (
170+
typeof externalConfig === "object" &&
171+
externalConfig !== null &&
172+
!Array.isArray(externalConfig) &&
173+
Object.prototype.hasOwnProperty.call(externalConfig, "interop")
174+
) {
175+
const { interop: interopValue, ...rest } =
176+
/** @type {Record<string, string | string[]> & { interop?: ExternalItemInterop }} */ (
177+
externalConfig
178+
);
179+
interop = interopValue;
180+
externalConfig = rest;
181+
}
164182
// When no explicit type is specified, extract it from the externalConfig
165183
if (type === undefined) {
166184
if (
@@ -239,7 +257,8 @@ class ExternalModuleFactoryPlugin {
239257
externalConfig,
240258
resolvedType,
241259
dependency.request,
242-
dependencyMeta
260+
dependencyMeta,
261+
interop
243262
)
244263
);
245264
};

‎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: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1446,6 +1446,10 @@
14461446
"instanceof": "Function",
14471447
"tsType": "import(\"../lib/ExternalModuleFactoryPlugin\").ExternalItemFunctionPromise"
14481448
},
1449+
"ExternalItemInterop": {
1450+
"description": "How an external's exports interoperate with ES module imports, independent of the importing module's strictness (similar to Rollup's `output.interop`). 'default': treat as CommonJS, the default import is the whole exports (Node.js semantics). 'esModule': treat as an ES module namespace, the default import is unboxed to `.default`.",
1451+
"enum": ["default", "esModule"]
1452+
},
14491453
"ExternalItemValue": {
14501454
"description": "The dependency used for the external.",
14511455
"anyOf": [
@@ -1466,7 +1470,30 @@
14661470
"type": "string"
14671471
},
14681472
{
1469-
"type": "object"
1473+
"description": "The target of the external with a type, optionally with an 'interop' hint describing how its exports interoperate with ES module imports.",
1474+
"type": "object",
1475+
"additionalProperties": {
1476+
"description": "The target of the external for a specific external type.",
1477+
"anyOf": [
1478+
{
1479+
"type": "array",
1480+
"items": {
1481+
"description": "A part of the target of the external.",
1482+
"type": "string",
1483+
"minLength": 1
1484+
}
1485+
},
1486+
{
1487+
"description": "The target of the external.",
1488+
"type": "string"
1489+
}
1490+
]
1491+
},
1492+
"properties": {
1493+
"interop": {
1494+
"$ref": "#/definitions/ExternalItemInterop"
1495+
}
1496+
}
14701497
}
14711498
]
14721499
},

0 commit comments

Comments
 (0)