Skip to content

Commit a1f0fb1

Browse files
feat: keep module side-effect information in the build output (#21789)
* feat: keep module side-effect information in the build output Annotate the instantiation of a module webpack knows to be side-effect free with `/*#__PURE__*/`, so a bundler consuming the emitted bundle can drop it when nothing reads its exports. Refs #17121 * feat: annotate every module instantiation webpack emits as a statement Carry the side-effect information into the deferred import, the eager slot of a wrapped concatenation member and the three entry-startup calls as well. Annotating an expression a caller may go on to invoke is not safe: a minifier binds the annotation to the outermost call, so `f(id)(x)` loses `(x)` with it. The entry-startup calls skip it where the module id is assigned inside the argument, and the entry IIFE keeps it for writing into `__webpack_exports__` rather than returning it. Refs #17121 * test: cover the deferred module instantiations Drop the annotation from the eager slot of a wrapped concatenation member: the root is the only member ever reached that way, and every shape that wraps it routes a `require()` through its own imports, so it is never side-effect free there and the annotation could not be emitted. Refs #17121 * chore: regenerate types for the annotation helper Refs #17121 * fix: keep the side-effect annotations in a minified library Terser drops `/*#__PURE__*/` unless asked not to, so a production library build erased the information it had just been given. Preserve annotations in the default JavaScript minimizer options whenever the output is consumed as a library. Refs #17121 * feat: report an entry whose exports a consumer cannot drop An entry other modules reference is not inlined, so its exports are read off the exports object and no bundler consuming the library can drop them. Report that through the analyzable-ESM bailout channel, where the answer is actionable. Refs #17121 * chore: fold the changeset into one entry Refs #17121 * test: build the annotation matcher without hand-rolled escaping CodeQL flagged the escape set for omitting backslashes. Spell the pieces out already escaped for a regexp instead, which drops the replace entirely. Refs #17121 * test: snapshot the deferred bundles and shorten the changeset Review feedback: the emitted code is what these two assertions check, so let the whole bundle be the snapshot rather than pinning one substring of it, and bring the changeset summary back under 80 characters. Refs #17121 * docs: tighten the annotation comments Review feedback: keep both to the two short lines the guide asks for, without losing the minifier binding rule a new call site has to know. Refs #17121 * test: name the deferred bundle snapshots The two compilers run concurrently, so an unnamed snapshot keys on call order and the two bundles swapped places between runs. Key each on its bundle name instead. Refs #17121 * test: shorten the snapshot helper's JSDoc Review feedback: comments in test/ are at most two short lines, so keep the type annotation and drop the prose. Refs #17121 * fix: do not annotate the call that starts an entry An entry runs by contract, not because something imports it, so a minifier that drops the startup call leaves the entry unexecuted — `all-combined` built nine cases whose bundles then registered no tests at all. Side-effect freedom says an importer may skip a module; it does not say the entry may never run. Refs #17121 * test: keep the deferred snapshots off the running node version The case pinned its target to the node running it, so the emitted runtime tracked that version — Object.hasOwn on a new one, the hasOwnProperty fallback on Node 14 — and the snapshot could not hold across the matrix. Use the conservative target the harness defaults to, as the repo's other bundle-snapshot case does. Refs #17121 * test: assert the surviving annotation on the asset, not at runtime Reading the bundle back with `require("fs")` made the ESM output import `createRequire` from `node:module`, which Node 10 does not have. * test: refresh the deferred snapshots for the leaner define-getters runtime The rebase picks up #21803, which shortens `__webpack_require__.d`. The annotations under test are unchanged. * fix: pass the answer `_analyzableBailout` now requires Main gave the helper a third argument it hands back; the public wrapper only reports, so it answers with `null`. * feat: write the side-effect annotations only into ESM output Output another build reads back is the only output the annotation can pay for. Over configCases the gate is -1.51 KiB raw / -635 B gzip: 73 assets lose an annotation nothing consumed, 21 defer-import ones grow because their own minifier pass was using it. * test: drop the annotations from a non-ESM snapshot `static-export-bindings` builds a script bundle, so the ESM gate no longer writes them there. * docs: shorten a test comment to the two-line limit * docs: shorten a comment to the three-line limit * fix: preserve the annotations only for an ESM library A script-loaded output — a federation container above all — carries no annotations of its own, so telling terser to keep them only kept the ones webpack has always emitted and terser used to drop.
1 parent 3d2bec0 commit a1f0fb1

37 files changed

Lines changed: 2609 additions & 8 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+
Keep module side-effect information in ESM output as PURE annotations.

‎lib/config/defaults.js‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -578,6 +578,10 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
578578
css:
579579
/** @type {boolean} */
580580
(options.experiments.css),
581+
esmLibrary:
582+
/** @type {string[]} */
583+
(options.output.enabledLibraryTypes).length > 0 &&
584+
Boolean(options.output.module),
581585
records: Boolean(options.recordsInputPath || options.recordsOutputPath)
582586
});
583587

@@ -2444,12 +2448,13 @@ const applyPerformanceDefaults = (performance, { production }) => {
24442448
* @param {boolean} options.production is production
24452449
* @param {boolean} options.development is development
24462450
* @param {boolean} options.css is css enabled
2451+
* @param {boolean} options.esmLibrary whether the output is an ECMAScript module consumed as a library
24472452
* @param {boolean} options.records using records
24482453
* @returns {void}
24492454
*/
24502455
const applyOptimizationDefaults = (
24512456
optimization,
2452-
{ production, development, css, records }
2457+
{ production, development, css, esmLibrary, records }
24532458
) => {
24542459
D(optimization, "removeAvailableModules", false);
24552460
D(optimization, "removeEmptyChunks", true);
@@ -2496,9 +2501,18 @@ const applyOptimizationDefaults = (
24962501
/** @type {NonNullable<Optimization["minimizeOptions"]>} */
24972502
(optimization.minimizeOptions);
24982503
if (optimization.minimize) {
2499-
// Canonicalize the per-asset-type options: the JS minimizer's defaults
2500-
// become visible in the resolved config rather than hidden in the wiring.
2501-
F(minimizeOptions, "javascript", () => ({ compress: { passes: 2 } }));
2504+
// Only ESM output carries these annotations, and only a consumer that
2505+
// re-bundles it reads them; terser drops them everywhere else, which is
2506+
// what a script-loaded output — a federation container — wants.
2507+
F(minimizeOptions, "javascript", () =>
2508+
esmLibrary
2509+
? {
2510+
compress: { passes: 2 },
2511+
// eslint-disable-next-line camelcase
2512+
format: { preserve_annotations: true }
2513+
}
2514+
: { compress: { passes: 2 } }
2515+
);
25022516
F(minimizeOptions, "css", () => ({}));
25032517
F(minimizeOptions, "html", () => ({}));
25042518
}

‎lib/javascript/JavascriptModulesPlugin.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1715,6 +1715,12 @@ class JavascriptModulesPlugin {
17151715
buf2.push(
17161716
"// This entry module is referenced by other modules so it can't be inlined"
17171717
);
1718+
// Its exports are then read off the exports object, and a property
1719+
// read is not something a consumer of the bundle can drop.
1720+
runtimeTemplate.analyzableBailout(
1721+
entryModule,
1722+
"the entry is referenced by other modules, so its exports are read off the exports object and a consumer cannot drop them"
1723+
);
17181724
result.allowInlineStartup = false;
17191725
}
17201726

‎lib/optimize/ConcatenatedModule.js‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2820,7 +2820,7 @@ ${defineGetters}`
28202820
result.add(
28212821
`\n// DEFERRED EXTERNAL MODULE: ${info.module.readableIdentifier(
28222822
requestShortener
2823-
)}\nvar ${info.deferredName} = ${loader};`
2823+
)}\nvar ${info.deferredName} = ${runtimeTemplate.sideEffectsAnnotation()}${loader};`
28242824
);
28252825
if (info.deferredNamespaceObjectUsed) {
28262826
runtimeRequirements.add(RuntimeGlobals.makeDeferredNamespaceObject);
@@ -2934,7 +2934,10 @@ ${defineGetters}`
29342934
// External module bindings may be wrapped in
29352935
// runtime-condition `if` blocks but referenced outside,
29362936
// so they must remain function-scoped (`var`).
2937-
const required = `__webpack_require__(${moduleId})`;
2937+
const required = `${runtimeTemplate.moduleSideEffectsAnnotation(
2938+
info.module,
2939+
moduleGraph
2940+
)}__webpack_require__(${moduleId})`;
29382941

29392942
// The wrapping happens per reference, so only the helper has
29402943
// to be declared here.

‎lib/template/RuntimeTemplate.js‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -835,6 +835,16 @@ class RuntimeTemplate {
835835
return true;
836836
}
837837

838+
/**
839+
* Reports an analyzable-ESM bailout from outside this class.
840+
* @param {Module | undefined} module the module the reference is emitted into
841+
* @param {string} reason why no literal could be baked
842+
* @returns {void}
843+
*/
844+
analyzableBailout(module, reason) {
845+
this._analyzableBailout(module, reason, null);
846+
}
847+
838848
/**
839849
* Records why a reference kept the runtime form, on the module that wrote it —
840850
* the channel `ModuleConcatenationPlugin` already reports through, so it reaches
@@ -1855,6 +1865,28 @@ class RuntimeTemplate {
18551865
return `${this.comment({ request })}${JSON.stringify(moduleId)}`;
18561866
}
18571867

1868+
/**
1869+
* The side-effect annotation for output another build reads back, which is the
1870+
* only output it can pay for — elsewhere it is bytes with no consumer.
1871+
* @returns {string} the annotation, or an empty string
1872+
*/
1873+
sideEffectsAnnotation() {
1874+
return this.outputOptions.module ? "/*#__PURE__*/" : "";
1875+
}
1876+
1877+
/**
1878+
* A module instantiation's side-effect annotation. Write it only where the
1879+
* statement ends the call: a minifier reads `f(id)(x)` as one and drops it.
1880+
* @param {Module} module the instantiated module
1881+
* @param {ModuleGraph} moduleGraph the module graph
1882+
* @returns {string} the annotation, or an empty string when it may have side effects
1883+
*/
1884+
moduleSideEffectsAnnotation(module, moduleGraph) {
1885+
return module.getSideEffectsConnectionState(moduleGraph) === false
1886+
? this.sideEffectsAnnotation()
1887+
: "";
1888+
}
1889+
18581890
/**
18591891
* Returns the expression.
18601892
* @param {object} options options object
@@ -2383,7 +2415,7 @@ class RuntimeTemplate {
23832415
// would deadlock; forcing the namespace throws instead.
23842416
outgoingAsyncModules.delete(originModule);
23852417

2386-
importContent = `/* deferred harmony import */ ${optDeclaration}${importVar} = ${getOptimizedDeferredModule(
2418+
importContent = `/* deferred harmony import */ ${optDeclaration}${importVar} = ${this.sideEffectsAnnotation()}${getOptimizedDeferredModule(
23872419
moduleId,
23882420
exportsType,
23892421
Array.from(outgoingAsyncModules, (mod) => chunkGraph.getModuleId(mod)),
@@ -2396,7 +2428,10 @@ class RuntimeTemplate {
23962428

23972429
return [importContent, ""];
23982430
}
2399-
importContent = `/* harmony import */ ${optDeclaration}${importVar} = ${RuntimeGlobals.require}(${moduleId});\n`;
2431+
importContent = `/* harmony import */ ${optDeclaration}${importVar} = ${this.moduleSideEffectsAnnotation(
2432+
module,
2433+
moduleGraph
2434+
)}${RuntimeGlobals.require}(${moduleId});\n`;
24002435

24012436
if (exportsType === "dynamic") {
24022437
runtimeRequirements.add(RuntimeGlobals.compatGetDefaultExport);
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { mul } from "./pure-cjs";
2+
3+
export function plus(a, b) {
4+
return a + b;
5+
}
6+
7+
export function times(a, b) {
8+
return mul(a, b);
9+
}
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// Not analyzable as side-effect free, so the case's `sideEffects: false` rule is
2+
// what tells webpack it is — the information the annotation carries into the output.
3+
exports.mul = function (a, b) {
4+
// Makes the module identifiable in the minified consumer bundle.
5+
if (a === "PURE_CJS_MODULE_MARKER") return a;
6+
return a * b;
7+
};
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"use strict";
2+
3+
module.exports.noTests = true;
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
"use strict";
2+
3+
/** @type {import("../../../../types").Configuration} */
4+
module.exports = {
5+
target: "node",
6+
mode: "production",
7+
output: {
8+
filename: "lib.mjs",
9+
library: { type: "module" },
10+
module: true
11+
},
12+
module: {
13+
rules: [{ test: /[\\/]pure-cjs\.js$/, sideEffects: false }]
14+
},
15+
experiments: {
16+
outputModule: true
17+
}
18+
};
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import { plus } from "library";
2+
3+
it("should keep the export it uses", () => {
4+
expect(plus(1, 2)).toBe(3);
5+
});
6+
7+
it("should drop the side-effect-free module behind the unused export", () => {
8+
const fs = require("fs");
9+
const source = fs.readFileSync(__filename, "utf-8");
10+
// Spelled out in pieces, so this assertion is not itself a hit.
11+
const marker = ["PURE", "CJS", "MODULE", "MARKER"].join("_");
12+
13+
expect(source).not.toContain(marker);
14+
});

0 commit comments

Comments
 (0)