Skip to content

Commit 038c301

Browse files
feat(performance): add five hints for problems bundling itself creates (#21821)
* feat(performance): add the asyncChunkWaterfalls hint A chunk cannot be requested until the one importing it has arrived and run, so an 'import()' chain costs a round trip per level before anything below it starts. The chunk group graph already holds the depth; only the end of each chain is reported, since every prefix of it is the same finding said again. * feat(performance): add the loadersOnNodeModules hint Dependencies ship built, so a rule without 'exclude: /node_modules/' spends build time redoing work — the most common reason a build is slow. The count is per loader, and a case pins that application modules the same loader handled are not counted. * feat(performance): add the inlinedAssets hint A data url is base64, so it costs about a third more than the file it replaces, cannot be cached on its own, and is downloaded again whenever the code around it changes. The parser already records whether it inlined, so the check asks the module rather than reading its type. * feat(performance): add the embeddedSourceMaps hint The 'eval' and 'inline' devtool families write the map into the bundle, so in a production build everyone loading the page downloads it. Cases pin that a separate '.map', and the same devtool in development, stay quiet. * feat(performance): add the topLevelThis hint At the top level of an ES module 'this' is 'undefined', so code moved from CommonJS that reads it silently gets nothing — Rollup warns and webpack was silent. Only bodies that rebind 'this' are skipped, so an arrow function at the top level still counts, and CommonJS is left alone because there 'this' is 'module.exports' and means what it says. * feat(performance): add the constReassignment and namespaceCall hints Both throw a TypeError where they run and webpack was silent about them. Rather than a scope analysis on the parse path, only names with exactly one binding in the module are considered: such a name cannot be shadowed, so every mention of it is that binding. A shadowed name is left alone instead of guessed at, which under-reports rather than failing a build with 'hints: "error"' over something legal. Also looks through scope hoisting in the four hints that read evidence left at parse time: a concatenation is one module in the chunk graph but several on disk, and the evidence sits on the ones that were parsed. * test: update the option-surface snapshots for the seven new hints The CLI flags are derived from the schema and the defaults snapshot carries the whole resolved config, so each new property shows up in both. * test: type the loader fixture parameters * feat(performance): drop the two hints that only a linter owes you 'constReassignment' and 'namespaceCall' report code that is broken with or without a bundler, which ESLint and TypeScript already say and webpack has no better view of. A hint earns its place by catching something bundling caused. 'topLevelThis' stays and now says what webpack knows rather than what a linter would: the file is being treated as an ES module — one 'import' or 'export' is enough for 'javascript/auto' to decide that — and 'this' is 'undefined' there rather than 'module.exports'. * feat(performance): drop the loadersOnNodeModules hint Transpiling a dependency is a choice rather than a defect — an ESM-only package often needs it — so a loader touching 'node_modules' is not something webpack can call wrong. It also reported what the build cost rather than a problem with what the build produced. * fix(performance): count 'this' in a class heritage clause and computed key A class rebinds 'this' in its body, but its heritage clause and its computed keys are evaluated where the class is written — so 'class C extends this.Base {}' reads the module's 'this' and was skipped along with the body. Reverting to the wholesale skip fails the new case. Also folds the four changesets into one, as the guide asks, and shortens a comment past the two-line limit. * test(performance): cover the hint ordering comparators Every case reported a single waterfall, asset or module, so the three sort comparators never ran and the documented order was untested. Each base case now reports several, with the tie-break arm exercised too.
1 parent 7b7f6dd commit 038c301

118 files changed

Lines changed: 1488 additions & 1 deletion

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
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 four performance hints for problems bundling itself creates.

‎declarations/WebpackOptions.d.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3287,6 +3287,11 @@ export interface PerformanceOptions {
32873287
* Filter function to select assets that are checked.
32883288
*/
32893289
assetFilter?: import("../lib/performance/SizeLimitsPlugin").AssetFilter;
3290+
/**
3291+
* Report chains of 'import()' calls where each chunk can only be requested once the one before it has arrived, so the levels cost round trips in series (requires 'hints' to be enabled).
3292+
* @since 5.110.0
3293+
*/
3294+
asyncChunkWaterfalls?: boolean;
32903295
/**
32913296
* Report 'require.context' calls with no filter, which bundle every file under a directory (requires 'hints' to be enabled).
32923297
* @since 5.110.0
@@ -3322,6 +3327,11 @@ export interface PerformanceOptions {
33223327
* @since 5.110.0
33233328
*/
33243329
dynamicExports?: boolean;
3330+
/**
3331+
* Report a production build whose 'devtool' writes the source map into the JavaScript, so everyone loading the page downloads it (requires 'hints' to be enabled).
3332+
* @since 5.110.0
3333+
*/
3334+
embeddedSourceMaps?: boolean;
33253335
/**
33263336
* Report modules shipped by more than one entrypoint, which every page that loads them downloads again (requires 'hints' to be enabled).
33273337
* @since 5.110.0
@@ -3341,6 +3351,11 @@ export interface PerformanceOptions {
33413351
* @since 5.110.0
33423352
*/
33433353
hotspots?: boolean;
3354+
/**
3355+
* Report assets inlined as data urls that are large enough for the base64 cost and the lost caching to outweigh the request they save (requires 'hints' to be enabled).
3356+
* @since 5.110.0
3357+
*/
3358+
inlinedAssets?: boolean;
33443359
/**
33453360
* Report a single module that makes up most of the chunk it is in (requires 'hints' to be enabled).
33463361
* @since 5.110.0
@@ -3399,6 +3414,11 @@ export interface PerformanceOptions {
33993414
* @since 5.110.0
34003415
*/
34013416
tinyChunks?: boolean;
3417+
/**
3418+
* Report modules that read 'this' at the top level of an ES module, where it is 'undefined' rather than the module object or the global one (requires 'hints' to be enabled).
3419+
* @since 5.110.0
3420+
*/
3421+
topLevelThis?: boolean;
34023422
/**
34033423
* Report initial chunks that mix 'node_modules' code with application code, so every application change re-downloads the dependencies too (requires 'hints' to be enabled).
34043424
* @since 5.110.0

‎lib/Module.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,7 @@ const makeSerializable = require("./util/makeSerializable");
201201
* @property {boolean=} isCircular true when the module is part of a circular dependency chain
202202
* @property {boolean=} usesEval true when the module calls `eval` directly
203203
* @property {number=} ineffectivePureAnnotations how many `#__PURE__` annotations sit where the parser does not read them
204+
* @property {number=} topLevelThis how many times the module reads `this` at its top level
204205
* @property {boolean=} usesTopLevelAwaitForOf module uses top-level `for await…of` or `await using`, which can't be lowered to a generator
205206
*/
206207

‎lib/WebpackOptionsApply.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -978,6 +978,12 @@ class WebpackOptionsApply extends OptionsApply {
978978
new LargeModulesPlugin(options.performance).apply(compiler);
979979
}
980980

981+
if (options.performance.asyncChunkWaterfalls) {
982+
const AsyncChunkWaterfallsPlugin = require("./performance/AsyncChunkWaterfallsPlugin");
983+
984+
new AsyncChunkWaterfallsPlugin(options.performance).apply(compiler);
985+
}
986+
981987
if (options.performance.broadContexts) {
982988
const BroadContextsPlugin = require("./performance/BroadContextsPlugin");
983989

@@ -1014,6 +1020,12 @@ class WebpackOptionsApply extends OptionsApply {
10141020
new TinyChunksPlugin(options.performance).apply(compiler);
10151021
}
10161022

1023+
if (options.performance.topLevelThis) {
1024+
const TopLevelThisPlugin = require("./performance/TopLevelThisPlugin");
1025+
1026+
new TopLevelThisPlugin(options.performance).apply(compiler);
1027+
}
1028+
10171029
if (options.performance.unsplitVendors) {
10181030
const UnsplitVendorsPlugin = require("./performance/UnsplitVendorsPlugin");
10191031

@@ -1032,6 +1044,18 @@ class WebpackOptionsApply extends OptionsApply {
10321044
new DynamicExportsPlugin(options.performance).apply(compiler);
10331045
}
10341046

1047+
if (options.performance.embeddedSourceMaps) {
1048+
const EmbeddedSourceMapsPlugin = require("./performance/EmbeddedSourceMapsPlugin");
1049+
1050+
new EmbeddedSourceMapsPlugin(options.performance).apply(compiler);
1051+
}
1052+
1053+
if (options.performance.inlinedAssets) {
1054+
const InlinedAssetsPlugin = require("./performance/InlinedAssetsPlugin");
1055+
1056+
new InlinedAssetsPlugin(options.performance).apply(compiler);
1057+
}
1058+
10351059
if (options.performance.missingSideEffects) {
10361060
const MissingSideEffectsPlugin = require("./performance/MissingSideEffectsPlugin");
10371061

‎lib/config/defaults.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2418,6 +2418,7 @@ const applyPerformanceDefaults = (performance, { production }) => {
24182418
// Stands in for every check left unset, so an explicit one still wins.
24192419
const all = performance.all !== undefined ? performance.all : false;
24202420

2421+
D(performance, "asyncChunkWaterfalls", all);
24212422
D(performance, "broadContexts", all);
24222423
D(performance, "cacheEffectiveness", all);
24232424
D(performance, "circularDependencies", all);
@@ -2426,10 +2427,12 @@ const applyPerformanceDefaults = (performance, { production }) => {
24262427
D(performance, "duplicatePackages", all);
24272428
D(performance, "dynamicExports", all);
24282429
D(performance, "entrypointOverlap", all);
2430+
D(performance, "embeddedSourceMaps", all);
24292431
D(performance, "evalUsage", all);
24302432
D(performance, "hotspots", all);
24312433
D(performance, "legacyJavascript", all);
24322434
D(performance, "largeModules", all);
2435+
D(performance, "inlinedAssets", all);
24332436
D(performance, "mixedExports", all);
24342437
D(performance, "missingSideEffects", all);
24352438
D(performance, "osDependentRules", all);
@@ -2438,6 +2441,7 @@ const applyPerformanceDefaults = (performance, { production }) => {
24382441
D(performance, "scopeHoistingBailouts", all);
24392442
D(performance, "splitChunksCapped", all);
24402443
D(performance, "tinyChunks", all);
2444+
D(performance, "topLevelThis", all);
24412445
D(performance, "unsplitVendors", all);
24422446
D(performance, "unusedAliases", all);
24432447
D(performance, "unusedDefines", all);
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
Author Alexander Akait @alexander-akait
4+
*/
5+
6+
"use strict";
7+
8+
const WebpackError = require("./WebpackError");
9+
10+
/**
11+
* @typedef {object} WaterfallDetails
12+
* @property {string[]} chain the chunk groups making up the chain, outermost first
13+
* @property {number} size the bytes the chain loads in total
14+
*/
15+
16+
class AsyncChunkWaterfallWarning extends WebpackError {
17+
/**
18+
* Creates an instance of AsyncChunkWaterfallWarning.
19+
* @param {WaterfallDetails[]} waterfalls the chains that are too deep
20+
* @param {number} depth the depth the deepest of them reaches
21+
*/
22+
constructor(waterfalls, depth) {
23+
const list = waterfalls
24+
.map((it) => `\n ${it.chain.join(" → ")} (${it.size} bytes)`)
25+
.join("");
26+
27+
super(
28+
`async chunk waterfall: ${waterfalls.length} ${waterfalls.length === 1 ? "chain loads" : "chains load"} ${depth} levels deep:${list}\nA chunk cannot be requested until the one importing it has arrived and run, so each level costs a round trip before anything below it starts. Importing the deeper modules from the entry, or giving them one 'webpackPrefetch' hint, lets them be fetched together.\nFor more info visit https://webpack.js.org/api/module-methods/#magic-comments`
29+
);
30+
31+
/** @type {string} */
32+
this.name = "AsyncChunkWaterfallWarning";
33+
}
34+
}
35+
36+
module.exports = AsyncChunkWaterfallWarning;
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
Author Alexander Akait @alexander-akait
4+
*/
5+
6+
"use strict";
7+
8+
const WebpackError = require("./WebpackError");
9+
10+
class EmbeddedSourceMapsWarning extends WebpackError {
11+
/**
12+
* Creates an instance of EmbeddedSourceMapsWarning.
13+
* @param {string} devtool the devtool that embeds them
14+
*/
15+
constructor(devtool) {
16+
super(
17+
`embedded source maps: 'devtool: "${devtool}"' writes the source map into the JavaScript itself, and this is a production build.\nThe map is then downloaded by everyone who loads the page, several times the size of the code it describes. A separate '.map' file is fetched only by whoever opens the devtools, and 'hidden-source-map' keeps it off the client entirely while still uploading to an error reporter.\nFor more info visit https://webpack.js.org/configuration/devtool/#production`
18+
);
19+
20+
/** @type {string} */
21+
this.name = "EmbeddedSourceMapsWarning";
22+
}
23+
}
24+
25+
module.exports = EmbeddedSourceMapsWarning;

‎lib/errors/InlinedAssetsWarning.js‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
Author Alexander Akait @alexander-akait
4+
*/
5+
6+
"use strict";
7+
8+
const WebpackError = require("./WebpackError");
9+
10+
/**
11+
* @typedef {object} InlinedAssetDetails
12+
* @property {string} name the asset, by path
13+
* @property {number} size the bytes it adds to the JavaScript
14+
*/
15+
16+
class InlinedAssetsWarning extends WebpackError {
17+
/**
18+
* Creates an instance of InlinedAssetsWarning.
19+
* @param {InlinedAssetDetails[]} assets the assets inlined as data urls
20+
* @param {number} total the bytes they add between them
21+
*/
22+
constructor(assets, total) {
23+
const list = assets
24+
.map((it) => `\n ${it.name} (${it.size} bytes)`)
25+
.join("");
26+
27+
super(
28+
`inlined assets: ${total} bytes of asset data are embedded in the JavaScript:${list}\nA data url is base64, so it costs about a third more than the file it replaces, cannot be cached on its own, and is downloaded again whenever the code around it changes. 'Rule.parser.dataUrlCondition.maxSize' decides which files are small enough to be worth that.\nFor more info visit https://webpack.js.org/guides/asset-modules/#general-asset-type`
29+
);
30+
31+
/** @type {string} */
32+
this.name = "InlinedAssetsWarning";
33+
}
34+
}
35+
36+
module.exports = InlinedAssetsWarning;

‎lib/errors/TopLevelThisWarning.js‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/*
2+
MIT License http://www.opensource.org/licenses/mit-license.php
3+
Author Alexander Akait @alexander-akait
4+
*/
5+
6+
"use strict";
7+
8+
const WebpackError = require("./WebpackError");
9+
10+
/**
11+
* @typedef {object} TopLevelThisDetails
12+
* @property {string} name the module, by request
13+
* @property {number} count how many times it reads `this` at the top level
14+
*/
15+
16+
class TopLevelThisWarning extends WebpackError {
17+
/**
18+
* Creates an instance of TopLevelThisWarning.
19+
* @param {TopLevelThisDetails[]} modules the modules that do it
20+
* @param {number} total how many such reads there are in all
21+
*/
22+
constructor(modules, total) {
23+
const list = modules.map((it) => `\n ${it.name} (${it.count})`).join("");
24+
25+
super(
26+
`top-level this: ${total} ${total === 1 ? "read" : "reads"} of 'this' at the top level of an ES module:${list}\nwebpack is treating these as ES modules, where 'this' is 'undefined' at the top level rather than 'module.exports' — so a file that worked as CommonJS reads nothing once it is bundled this way. A single 'import' or 'export' is enough to make 'javascript/auto' decide a file is an ES module. Use 'globalThis' where the global object was meant, 'import.meta' for anything about the module, or give the file a '.cjs' extension to keep it CommonJS.\nFor more info visit https://webpack.js.org/api/module-variables/#importmeta`
27+
);
28+
29+
/** @type {string} */
30+
this.name = "TopLevelThisWarning";
31+
}
32+
}
33+
34+
module.exports = TopLevelThisWarning;

0 commit comments

Comments
 (0)