Skip to content

Commit bf21f16

Browse files
feat(performance): add broadContexts, largeModules and hotspots hints (#21793)
* feat(performance): add broadContexts hint A context created without a filter takes whatever the directory holds — `require.context('./locale')` bundles every file under it, whether or not anything ever asks for one. The catch-all regExp webpack falls back to is what identifies that, so a context narrowed by a regExp, include or exclude is left alone, as is one webpack cannot recognize. A directory of a handful of files costs little however it is matched, so only contexts carrying at least twenty modules are reported. * fix(performance): catch every construction that opens a context The first cut keyed on the exact filter `require.context` falls back to, which misses the two constructions that reach a whole directory most often: `require('./locale/' + name)` and `import(\`./locale/\${name}.js\`)` both get a pattern webpack derives from the expression, `^./.*\.js$`, never the catch-all. Any pattern opening with a bare wildcard counts now. A lazy context was missed twice over — it also keeps each match in a block of its own, so reading only `dependencies` counted none of them. * feat(performance): add largeModules hint Names a module that is at least half of the chunk it sits in, so the report says which single file the chunk really is rather than that the chunk is big. 'SizeLimitsPlugin' already covers the absolute side — it fires per asset over 'maxAssetSize' — and this fires on the share, which it will do while every asset is still within budget. What counts as worth naming scales with 'maxAssetSize' rather than being a fixed number of bytes, so raising the budget raises the floor with it. Scope hoisting is unwrapped first, or the report would name the module that absorbed the offender instead of the offender. * feat(performance): add slowPlugins hint Charges each plugin the time its own code held the main thread. Wall time from tap to callback does not answer this: async taps nest, and summing them over one build came to 2.8x the build itself, with 'EntryPlugin' billed for everything 'make' encloses. Timing only the synchronous stretch of a tap and subtracting any tap that ran inside it brings the total under the wall clock and puts the optimisation passes at the top, where the work actually is. Interception reaches a tap only if it is registered first, so this taps 'compilation' at a stage before the rest and is wired ahead of the other performance plugins. Hooks are read through their property descriptors because the ones kept as aliases are getters that warn when read. * feat(performance): measure loaders and hooks too, as performance.hotspots Same measurement, three views. A loader is not a tap, so tap interception never reached one; 'LoaderRunner' now times a loader's own run through a sink a context carries, absent unless something asked for it. Every tap already knew which hook it belonged to, so the same self time groups by hook as well, and the report carries that as a second view of the one set of numbers rather than a second ranking. Loaders and plugins are ranked together because no name is ever both, so nothing is counted twice. 'slowPlugins' is renamed for what it now covers. * fix(performance): report each build's own time, and guard a missing budget Watching keeps the compiler, and nothing cleared the tally between builds, so a plugin burning the same 120 ms every rebuild was reported at 119, 239, then 358 ms — every plugin eventually crosses the threshold and the figures stop meaning anything. A watch case pins one build's time now; it reports 389 ms at step one without the fix. Two more from reading it back. A loader and a plugin kept their run counts in one map, so a shared name would have merged them; the count now sits beside the time, per kind. And 'largeModules' read 'maxAssetSize' straight, which is 'NaN' for a plugin built by hand and no size is ever below that — the floor silently stopped applying. Snapshots of the whole resolved config and of the CLI flags carry the three new options. * test(performance): cover the new hints' ranking, and drop what nothing reaches Every reported hint list is a ranking, but each case produced one entry, so no comparator ever ran. Three cases now produce two or three, with equal sizes so the order is the name tie-break alone. `largeModules` picked the chunk to name by first arrival, which chunk order does not fix; it names the first by name instead. The `chunkSize === 0` guard skipped a loop that was already empty, the `maxAssetSize` fallback restated a default `defaults.js` always applies, and `interceptAll` guarded against a hookless object no caller can pass. The comment on `INTERCEPT_STAGE` gave a reason that is not true: tapable applies a `register` interceptor to the taps a hook already has, so what the stage buys is the reset running before anything measures. * test(performance): isolate the tie counter, and say what hotspots measures `unused-reexports-tie` counted module evaluations on `global`, which Bun's worker threads share between test files: the cache suite ran first and left the count above what the config suite then asserted. The counter now lives in the bundle. `hotspots` measures synchronous stretches, so work a loader or tap resumes after an await is outside it. The message said it was what the loader or plugin costs, without that limit; it now states it. The three quiet cases said `expect(1).toBe(1)` or checked only the build. Nothing reads `compilation.hints`, so a hint pushed there with hints off went unnoticed; each now asserts that channel is empty. Also folds the three changesets into the one this pull request gets. * test(performance): trim the ranked cases' comments and placeholder * chore: keep the changeset summary under 80 characters
1 parent 6597fb5 commit bf21f16

330 files changed

Lines changed: 1877 additions & 6 deletions

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 the `broadContexts`, `largeModules` and `hotspots` performance hints.

‎cspell.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
"words": [
55
"EXTMATCH",
66
"fnmatch",
7+
"hotspot",
8+
"hotspots",
79
"SAPUI",
810
"accesskey",
911
"CSSOM",

‎declarations/WebpackOptions.d.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3275,6 +3275,11 @@ export interface PerformanceOptions {
32753275
* Filter function to select assets that are checked.
32763276
*/
32773277
assetFilter?: import("../lib/performance/SizeLimitsPlugin").AssetFilter;
3278+
/**
3279+
* Report 'require.context' calls with no filter, which bundle every file under a directory (requires 'hints' to be enabled).
3280+
* @since 5.110.0
3281+
*/
3282+
broadContexts?: boolean;
32783283
/**
32793284
* Report how much of the module graph the cache reused, and the modules that can never be reused (requires 'hints' to be enabled).
32803285
* @since 5.110.0
@@ -3314,6 +3319,16 @@ export interface PerformanceOptions {
33143319
* Sets the format of the hints: warnings, errors, stats-only or nothing at all.
33153320
*/
33163321
hints?: false | "warning" | "error" | "stats";
3322+
/**
3323+
* Report the loaders, plugins and hooks that hold the main thread, timing each one's own code rather than what it waited for (requires 'hints' to be enabled).
3324+
* @since 5.110.0
3325+
*/
3326+
hotspots?: boolean;
3327+
/**
3328+
* Report a single module that makes up most of the chunk it is in (requires 'hints' to be enabled).
3329+
* @since 5.110.0
3330+
*/
3331+
largeModules?: boolean;
33173332
/**
33183333
* File size limit (in bytes) when exceeded, that webpack will provide performance hints.
33193334
*/

‎lib/WebpackOptionsApply.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -925,6 +925,12 @@ class WebpackOptionsApply extends OptionsApply {
925925
}
926926

927927
if (options.performance) {
928+
if (options.performance.hotspots) {
929+
const HotspotsPlugin = require("./performance/HotspotsPlugin");
930+
931+
new HotspotsPlugin(options.performance).apply(compiler);
932+
}
933+
928934
const SizeLimitsPlugin = require("./performance/SizeLimitsPlugin");
929935

930936
new SizeLimitsPlugin(options.performance).apply(compiler);
@@ -959,6 +965,18 @@ class WebpackOptionsApply extends OptionsApply {
959965
new EntrypointOverlapPlugin(options.performance).apply(compiler);
960966
}
961967

968+
if (options.performance.largeModules) {
969+
const LargeModulesPlugin = require("./performance/LargeModulesPlugin");
970+
971+
new LargeModulesPlugin(options.performance).apply(compiler);
972+
}
973+
974+
if (options.performance.broadContexts) {
975+
const BroadContextsPlugin = require("./performance/BroadContextsPlugin");
976+
977+
new BroadContextsPlugin(options.performance).apply(compiler);
978+
}
979+
962980
if (options.performance.unsplitVendors) {
963981
const UnsplitVendorsPlugin = require("./performance/UnsplitVendorsPlugin");
964982

‎lib/config/defaults.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2401,13 +2401,16 @@ const applyPerformanceDefaults = (performance, { production }) => {
24012401
// Stands in for every check left unset, so an explicit one still wins.
24022402
const all = performance.all !== undefined ? performance.all : false;
24032403

2404+
D(performance, "broadContexts", all);
24042405
D(performance, "cacheEffectiveness", all);
24052406
D(performance, "circularDependencies", all);
24062407
D(performance, "conflictingResourceHints", all);
24072408
D(performance, "duplicateModules", all);
24082409
D(performance, "duplicatePackages", all);
24092410
D(performance, "dynamicExports", all);
24102411
D(performance, "entrypointOverlap", all);
2412+
D(performance, "hotspots", all);
2413+
D(performance, "largeModules", all);
24112414
D(performance, "missingSideEffects", all);
24122415
D(performance, "osDependentRules", all);
24132416
D(performance, "redundantDynamicImports", all);

‎lib/errors/BroadContextsWarning.js‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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 formatSize = require("../util/formatSize");
9+
const WebpackError = require("./WebpackError");
10+
11+
/**
12+
* @typedef {object} BroadContextDetails
13+
* @property {string} name the context as written, shortened for the report
14+
* @property {number} modules how many distinct modules it matched
15+
* @property {number} size bytes those modules contribute
16+
*/
17+
18+
class BroadContextsWarning extends WebpackError {
19+
/**
20+
* Creates an instance of BroadContextsWarning.
21+
* @param {BroadContextDetails[]} contexts the worst offenders, largest first
22+
* @param {number} total how many broad contexts there are in all
23+
*/
24+
constructor(contexts, total) {
25+
const list = contexts
26+
.map(
27+
(context) =>
28+
`\n ${context.name} (${context.modules} modules, ${formatSize(
29+
context.size
30+
)})`
31+
)
32+
.join("");
33+
34+
super(
35+
`broad contexts: ${total} ${total === 1 ? "context matches" : "contexts match"} every file under a directory:${list}\nA pattern opening with a bare wildcard takes whatever the directory holds, including files nothing ever requests — a sync context bundles them all, a lazy one gives each its own chunk. Narrowing the pattern, or 'ContextReplacementPlugin', limits it to what is reachable.\nFor more info visit https://webpack.js.org/plugins/context-replacement-plugin/`
36+
);
37+
38+
/** @type {string} */
39+
this.name = "BroadContextsWarning";
40+
}
41+
}
42+
43+
module.exports = BroadContextsWarning;

‎lib/errors/HotspotsWarning.js‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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} HotspotDetails
12+
* @property {"loader" | "plugin"} kind what the name refers to
13+
* @property {string} name the loader or plugin, as it identified itself
14+
* @property {number} ms milliseconds it held the main thread
15+
* @property {number} runs how many times it ran
16+
*/
17+
18+
/**
19+
* @typedef {object} HookDetails
20+
* @property {string} name the hook
21+
* @property {number} ms milliseconds its taps held the main thread
22+
*/
23+
24+
class HotspotsWarning extends WebpackError {
25+
/**
26+
* Creates an instance of HotspotsWarning.
27+
* @param {HotspotDetails[]} hotspots the worst offenders, slowest first
28+
* @param {number} total how many are over the threshold in all
29+
* @param {HookDetails[]} hooks the same time grouped by hook instead
30+
*/
31+
constructor(hotspots, total, hooks) {
32+
const list = hotspots
33+
.map(
34+
(hotspot) =>
35+
`\n ${hotspot.kind} ${hotspot.name} (${Math.round(hotspot.ms)} ms over ${
36+
hotspot.runs
37+
} ${hotspot.runs === 1 ? "run" : "runs"})`
38+
)
39+
.join("");
40+
41+
const byHook =
42+
hooks.length > 0
43+
? `\nThe same time, grouped by the hook it ran under:${hooks
44+
.map((hook) => `\n ${hook.name} (${Math.round(hook.ms)} ms)`)
45+
.join("")}`
46+
: "";
47+
48+
super(
49+
`hotspots: ${total} ${total === 1 ? "thing holds" : "things hold"} the main thread long enough to be worth looking at:${list}${byHook}\nThis is the time each one held the main thread itself, with anything it called out to charged to that instead — so it is what the loader or plugin costs, not what it waited for. Only synchronous stretches count, so work resumed after an await is missing from it. 'ProfilingPlugin' records the same work as a trace when the ordering matters.\nFor more info visit https://webpack.js.org/plugins/profiling-plugin/`
50+
);
51+
52+
/** @type {string} */
53+
this.name = "HotspotsWarning";
54+
}
55+
}
56+
57+
module.exports = HotspotsWarning;

‎lib/errors/LargeModulesWarning.js‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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 formatSize = require("../util/formatSize");
9+
const WebpackError = require("./WebpackError");
10+
11+
/**
12+
* @typedef {object} LargeModuleDetails
13+
* @property {string} name the module, shortened for the report
14+
* @property {string} chunk the chunk it weighs down
15+
* @property {number} size bytes the module contributes
16+
* @property {number} chunkSize bytes the whole chunk contributes
17+
*/
18+
19+
class LargeModulesWarning extends WebpackError {
20+
/**
21+
* Creates an instance of LargeModulesWarning.
22+
* @param {LargeModuleDetails[]} modules the worst offenders, largest first
23+
* @param {number} total how many dominating modules there are in all
24+
*/
25+
constructor(modules, total) {
26+
const list = modules
27+
.map((module) => {
28+
const share = Math.round((module.size / module.chunkSize) * 100);
29+
30+
return `\n ${module.name} is ${share}% of '${module.chunk}' (${formatSize(
31+
module.size
32+
)} of ${formatSize(module.chunkSize)})`;
33+
})
34+
.join("");
35+
36+
super(
37+
`large modules: ${total} ${total === 1 ? "module carries" : "modules carry"} most of the chunk ${total === 1 ? "it is" : "they are"} in:${list}\nEverything else in the chunk together weighs less than this one module, so splitting it out with 'optimization.splitChunks', loading it on demand, or replacing it is what changes the size.\nFor more info visit https://webpack.js.org/guides/code-splitting/`
38+
);
39+
40+
/** @type {string} */
41+
this.name = "LargeModulesWarning";
42+
}
43+
}
44+
45+
module.exports = LargeModulesWarning;

‎lib/loaders/LoaderRunner.js‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ const { readFile } = require("fs");
99
const { parseResource } = require("../util/identifier");
1010
const loadLoader = require("./loadLoader");
1111

12+
// Set on a loader context to have each loader's own run measured. Absent
13+
// unless something asked for the measurement, and read once per loader.
14+
const LOADER_TIMING = Symbol("loader timing");
15+
1216
/** @typedef {string | ({ loader: string } & Record<string, EXPECTED_ANY>)} LoaderItemInput */
1317

1418
/**
@@ -240,9 +244,17 @@ function runSyncOrAsync(fn, context, args, callback) {
240244
return innerCallback;
241245
};
242246

247+
const timing =
248+
/** @type {{ [LOADER_TIMING]?: (loader: EXPECTED_ANY, run: () => EXPECTED_ANY) => EXPECTED_ANY }} */
249+
(context)[LOADER_TIMING];
250+
243251
try {
244252
const result = (function LOADER_EXECUTION() {
245-
return fn.apply(context, args);
253+
return timing
254+
? timing(context.loaders[context.loaderIndex], () =>
255+
fn.apply(context, args)
256+
)
257+
: fn.apply(context, args);
246258
})();
247259
if (isSync) {
248260
isDone = true;
@@ -427,6 +439,7 @@ function joinRequests(loaders, start, end, resource) {
427439
return result + resource;
428440
}
429441

442+
module.exports.LOADER_TIMING = LOADER_TIMING;
430443
module.exports.LoaderObject = LoaderObject;
431444

432445
module.exports.createLoaderContext = createLoaderContext;

0 commit comments

Comments
 (0)