Skip to content

Commit 2d76874

Browse files
feat: align the public exports with the lib/ directory structure (#22261)
* feat: export the asset, json, bun, deno and TypeScript plugins Four of six per-module-type plugins were on the public API (css, html, javascript, wasm) and two were not, and the node and electron target presets were exported while bun and deno were not. Each gets the namespace its directory already implies. TypeScriptPlugin goes under experiments, beside schemes and ids, because experiments.typescript is what gates it. * feat: expose CssLoadingRuntimeModule under css, deprecate it under web It is the one member of the web scope whose file is not in lib/web/. The old path stays and now carries @deprecated. Making that tag reach types.d.ts needed the generator: a namespace's exports are emitted as one joined `export { … }`, which has nowhere to put a comment. The doc now rides the specifier inside the braces, which is the placement TypeScript reads a deprecation from — it ignores one written on the export statement itself. That surfaced a stale JSDoc block in InnerGraph, left behind when getDependencyUsedByExportsCondition lost its third parameter, which the checker was attaching to the topLevelSymbolTag export. * feat: move eleven loose exports under their scope, deprecate the flat names Cache, PlatformPlugin, WebpackOptionsApply, defineConfig, validateSchema, ConcatenationScope, OptimizationStages, RuntimeGlobals, RuntimeModule, AutomaticPrefetchPlugin and PrefetchPlugin each sat at the top level while their directory already had a scope. Both paths resolve to the same object; the flat one now carries @deprecated. Two more generator branches were dropping the tag: a namespace member that is not a class is emitted as `export const`, and one that is itself a namespace as its own declaration, and neither prepended the comment. All three branches now share one rule — a doc is emitted only when it carries a tag a consumer acts on (@SInCE, @deprecated, @experimental), since these positions have no line of their own and a description would render as one very long one. That list is now stated once. * feat(config): keep defineConfig at the top level undeprecated Every config file calls it, so a scope would put three names in front of each one. It is exposed under config as well, and both resolve to the same function. * feat(util): export RequestShortener The root shim told plugin authors to migrate to compiler.webpack.RequestShortener, which no export answered — the class is in lib/util/, so util is the scope, and the shim now names it. * test: cover the scoped exports and their kept aliases Every getter this pull request adds is a line only a property read executes, and nothing in configCases reads one, so the patch went in at 0% covered. The test asserts each scope resolves and that each kept flat name is the same object as its scoped path, which is the contract rather than the percentage. Also shortens the changeset: a combined entry may run past 80 characters slightly, and 183 is not slightly.
1 parent 38a80d3 commit 2d76874

7 files changed

Lines changed: 440 additions & 35 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+
Export more plugins under their scope, move eleven loose exports under theirs, deprecate the old.

‎lib/RequestShortener.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@
66
"use strict";
77

88
// TODO in the next major release: remove
9-
// Some old plugins use `require("webpack/lib/RequestShortener")`, in the next major release developer should migrate to `compiler.webpack.RequestShortener`
9+
// Some old plugins use `require("webpack/lib/RequestShortener")`, in the next major release developer should migrate to `compiler.webpack.util.RequestShortener`
1010
module.exports = require("./util/RequestShortener");

‎lib/index.js‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,8 @@ module.exports = mergeExports(fn, {
182182
get webpack() {
183183
return require("./webpack");
184184
},
185+
// Stays at the top level rather than only under `config`: every config file
186+
// calls it, and a scope would put three names in front of each one.
185187
get defineConfig() {
186188
return require("./config/defineConfig");
187189
},
@@ -214,6 +216,11 @@ module.exports = mergeExports(fn, {
214216
}
215217
};
216218
},
219+
/**
220+
* Validates a value against a JSON schema.
221+
* @deprecated use `config.validateSchema` — TODO in the next major release: remove
222+
* @returns {typeof import("./config/validateSchema")} the schema validator
223+
*/
217224
get validateSchema() {
218225
const validateSchema = require("./config/validateSchema");
219226

@@ -226,6 +233,11 @@ module.exports = mergeExports(fn, {
226233
get cli() {
227234
return getCli();
228235
},
236+
/**
237+
* Resolves every module of the last build eagerly.
238+
* @deprecated use `prefetch.AutomaticPrefetchPlugin` — TODO in the next major release: remove
239+
* @returns {typeof import("./prefetch/AutomaticPrefetchPlugin")} the moved export
240+
*/
229241
get AutomaticPrefetchPlugin() {
230242
return require("./prefetch/AutomaticPrefetchPlugin");
231243
},
@@ -235,6 +247,11 @@ module.exports = mergeExports(fn, {
235247
get BannerPlugin() {
236248
return require("./output/BannerPlugin");
237249
},
250+
/**
251+
* The cache a compilation stores and restores through.
252+
* @deprecated use `cache.Cache` — TODO in the next major release: remove
253+
* @returns {typeof import("./cache/Cache")} the moved export
254+
*/
238255
get Cache() {
239256
return require("./cache/Cache");
240257
},
@@ -253,6 +270,11 @@ module.exports = mergeExports(fn, {
253270
get Compiler() {
254271
return require("./Compiler");
255272
},
273+
/**
274+
* The protocol scope hoisting renders through.
275+
* @deprecated use `optimize.ConcatenationScope` — TODO in the next major release: remove
276+
* @returns {typeof import("./optimize/ConcatenationScope")} the moved export
277+
*/
256278
get ConcatenationScope() {
257279
return require("./optimize/ConcatenationScope");
258280
},
@@ -360,15 +382,30 @@ module.exports = mergeExports(fn, {
360382
get MultiCompiler() {
361383
return require("./MultiCompiler");
362384
},
385+
/**
386+
* The stage constants the optimization hooks are tapped at.
387+
* @deprecated use `optimize.OptimizationStages` — TODO in the next major release: remove
388+
* @returns {typeof import("./optimize/OptimizationStages")} the moved export
389+
*/
363390
get OptimizationStages() {
364391
return require("./optimize/OptimizationStages");
365392
},
366393
get Parser() {
367394
return require("./module/Parser");
368395
},
396+
/**
397+
* Pins the target platform a `target: false` build cannot infer.
398+
* @deprecated use `config.PlatformPlugin` — TODO in the next major release: remove
399+
* @returns {typeof import("./config/PlatformPlugin")} the moved export
400+
*/
369401
get PlatformPlugin() {
370402
return require("./config/PlatformPlugin");
371403
},
404+
/**
405+
* Resolves one request eagerly at build time.
406+
* @deprecated use `prefetch.PrefetchPlugin` — TODO in the next major release: remove
407+
* @returns {typeof import("./prefetch/PrefetchPlugin")} the moved export
408+
*/
372409
get PrefetchPlugin() {
373410
return require("./prefetch/PrefetchPlugin");
374411
},
@@ -378,9 +415,19 @@ module.exports = mergeExports(fn, {
378415
get ProvidePlugin() {
379416
return require("./provide/ProvidePlugin");
380417
},
418+
/**
419+
* The symbols a runtime module may declare a requirement on.
420+
* @deprecated use `runtime.RuntimeGlobals` — TODO in the next major release: remove
421+
* @returns {typeof import("./runtime/RuntimeGlobals")} the moved export
422+
*/
381423
get RuntimeGlobals() {
382424
return require("./runtime/RuntimeGlobals");
383425
},
426+
/**
427+
* The base class every emitted runtime module extends.
428+
* @deprecated use `runtime.RuntimeModule` — TODO in the next major release: remove
429+
* @returns {typeof import("./runtime/RuntimeModule")} the moved export
430+
*/
384431
get RuntimeModule() {
385432
return require("./runtime/RuntimeModule");
386433
},
@@ -415,6 +462,11 @@ module.exports = mergeExports(fn, {
415462
get WebpackError() {
416463
return require("./errors/WebpackError");
417464
},
465+
/**
466+
* Reads a resolved configuration into the plugins it implies.
467+
* @deprecated use `config.WebpackOptionsApply` — TODO in the next major release: remove
468+
* @returns {typeof import("./config/WebpackOptionsApply")} the moved export
469+
*/
418470
get WebpackOptionsApply() {
419471
return require("./config/WebpackOptionsApply");
420472
},
@@ -434,12 +486,27 @@ module.exports = mergeExports(fn, {
434486
},
435487

436488
cache: {
489+
get Cache() {
490+
return require("./cache/Cache");
491+
},
437492
get MemoryCachePlugin() {
438493
return require("./cache/MemoryCachePlugin");
439494
}
440495
},
441496

442497
config: {
498+
get PlatformPlugin() {
499+
return require("./config/PlatformPlugin");
500+
},
501+
get WebpackOptionsApply() {
502+
return require("./config/WebpackOptionsApply");
503+
},
504+
get defineConfig() {
505+
return require("./config/defineConfig");
506+
},
507+
get validateSchema() {
508+
return require("./config/validateSchema");
509+
},
443510
get getNormalizedWebpackOptions() {
444511
return require("./config/normalization").getNormalizedWebpackOptions;
445512
},
@@ -511,6 +578,12 @@ module.exports = mergeExports(fn, {
511578
},
512579

513580
optimize: {
581+
get ConcatenationScope() {
582+
return require("./optimize/ConcatenationScope");
583+
},
584+
get OptimizationStages() {
585+
return require("./optimize/OptimizationStages");
586+
},
514587
get AggressiveMergingPlugin() {
515588
return require("./optimize/AggressiveMergingPlugin");
516589
},
@@ -551,6 +624,12 @@ module.exports = mergeExports(fn, {
551624
},
552625

553626
runtime: {
627+
get RuntimeGlobals() {
628+
return require("./runtime/RuntimeGlobals");
629+
},
630+
get RuntimeModule() {
631+
return require("./runtime/RuntimeModule");
632+
},
554633
get GetChunkFilenameRuntimeModule() {
555634
return require("./runtime/GetChunkFilenameRuntimeModule");
556635
},
@@ -560,6 +639,12 @@ module.exports = mergeExports(fn, {
560639
},
561640

562641
prefetch: {
642+
get AutomaticPrefetchPlugin() {
643+
return require("./prefetch/AutomaticPrefetchPlugin");
644+
},
645+
get PrefetchPlugin() {
646+
return require("./prefetch/PrefetchPlugin");
647+
},
563648
get ChunkPrefetchPreloadPlugin() {
564649
return require("./prefetch/ChunkPrefetchPreloadPlugin");
565650
}
@@ -578,6 +663,11 @@ module.exports = mergeExports(fn, {
578663
get JsonpTemplatePlugin() {
579664
return require("./web/JsonpTemplatePlugin");
580665
},
666+
/**
667+
* The runtime module that loads a chunk's CSS.
668+
* @deprecated use `css.CssLoadingRuntimeModule`, the scope this module lives in — TODO in the next major release: remove
669+
* @returns {typeof import("./css/CssLoadingRuntimeModule")} the runtime module
670+
*/
581671
get CssLoadingRuntimeModule() {
582672
return require("./css/CssLoadingRuntimeModule");
583673
}
@@ -622,6 +712,18 @@ module.exports = mergeExports(fn, {
622712
}
623713
},
624714

715+
bun: {
716+
get BunTargetPlugin() {
717+
return require("./bun/BunTargetPlugin");
718+
}
719+
},
720+
721+
deno: {
722+
get DenoTargetPlugin() {
723+
return require("./deno/DenoTargetPlugin");
724+
}
725+
},
726+
625727
wasm: {
626728
get AsyncWebAssemblyModulesPlugin() {
627729
return require("./wasm/AsyncWebAssemblyModulesPlugin");
@@ -631,7 +733,22 @@ module.exports = mergeExports(fn, {
631733
}
632734
},
633735

736+
asset: {
737+
get AssetModulesPlugin() {
738+
return require("./asset/AssetModulesPlugin");
739+
}
740+
},
741+
742+
json: {
743+
get JsonModulesPlugin() {
744+
return require("./json/JsonModulesPlugin");
745+
}
746+
},
747+
634748
css: {
749+
get CssLoadingRuntimeModule() {
750+
return require("./css/CssLoadingRuntimeModule");
751+
},
635752
get CssModulesPlugin() {
636753
return require("./css/CssModulesPlugin");
637754
},
@@ -759,6 +876,9 @@ module.exports = mergeExports(fn, {
759876
get LazySet() {
760877
return require("./util/LazySet");
761878
},
879+
get RequestShortener() {
880+
return require("./util/RequestShortener");
881+
},
762882
get compileBooleanMatcher() {
763883
return require("./util/compileBooleanMatcher");
764884
},
@@ -786,6 +906,11 @@ module.exports = mergeExports(fn, {
786906
get SyncModuleIdsPlugin() {
787907
return require("./ids/SyncModuleIdsPlugin");
788908
}
909+
},
910+
typescript: {
911+
get TypeScriptPlugin() {
912+
return require("./typescript/TypeScriptPlugin");
913+
}
789914
}
790915
}
791916
});

‎lib/optimize/InnerGraph.js‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -485,12 +485,4 @@ module.exports.getInnerGraphUtils = (compilation) => {
485485
return utils;
486486
};
487487

488-
/**
489-
* Usage callback map.
490-
* @param {Dependency} dependency the dependency
491-
* @param {UsedByExports | undefined} usedByExports usedByExports info
492-
* @param {ModuleGraph} moduleGraph moduleGraph
493-
* @returns {null | false | GetConditionFn} function to determine if the connection is active
494-
*/
495-
496488
module.exports.topLevelSymbolTag = topLevelSymbolTag;
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
"use strict";
2+
3+
const webpack = require("../../lib/index");
4+
5+
// Each scope mirrors the directory its file lives in, so a name that stops
6+
// resolving means `lib/index.js` drifted from the tree. Read through a thunk
7+
// rather than by indexing, which keeps every access precisely typed.
8+
const SCOPED = [
9+
{ name: "asset.AssetModulesPlugin", read: () => webpack.asset.AssetModulesPlugin },
10+
{ name: "bun.BunTargetPlugin", read: () => webpack.bun.BunTargetPlugin },
11+
{ name: "cache.Cache", read: () => webpack.cache.Cache },
12+
{ name: "config.PlatformPlugin", read: () => webpack.config.PlatformPlugin },
13+
{ name: "config.WebpackOptionsApply", read: () => webpack.config.WebpackOptionsApply },
14+
{ name: "config.defineConfig", read: () => webpack.config.defineConfig },
15+
{ name: "config.validateSchema", read: () => webpack.config.validateSchema },
16+
{ name: "css.CssLoadingRuntimeModule", read: () => webpack.css.CssLoadingRuntimeModule },
17+
{ name: "deno.DenoTargetPlugin", read: () => webpack.deno.DenoTargetPlugin },
18+
{ name: "experiments.typescript.TypeScriptPlugin", read: () => webpack.experiments.typescript.TypeScriptPlugin },
19+
{ name: "json.JsonModulesPlugin", read: () => webpack.json.JsonModulesPlugin },
20+
{ name: "optimize.ConcatenationScope", read: () => webpack.optimize.ConcatenationScope },
21+
{ name: "optimize.OptimizationStages", read: () => webpack.optimize.OptimizationStages },
22+
{ name: "prefetch.AutomaticPrefetchPlugin", read: () => webpack.prefetch.AutomaticPrefetchPlugin },
23+
{ name: "prefetch.PrefetchPlugin", read: () => webpack.prefetch.PrefetchPlugin },
24+
{ name: "runtime.RuntimeGlobals", read: () => webpack.runtime.RuntimeGlobals },
25+
{ name: "runtime.RuntimeModule", read: () => webpack.runtime.RuntimeModule },
26+
{ name: "util.RequestShortener", read: () => webpack.util.RequestShortener }
27+
];
28+
29+
// The old path stays reachable and hands back the very same object.
30+
const KEPT_ALIASES = [
31+
{ from: "Cache", to: "cache.Cache", readFrom: () => webpack.Cache, readTo: () => webpack.cache.Cache },
32+
{ from: "PlatformPlugin", to: "config.PlatformPlugin", readFrom: () => webpack.PlatformPlugin, readTo: () => webpack.config.PlatformPlugin },
33+
{ from: "WebpackOptionsApply", to: "config.WebpackOptionsApply", readFrom: () => webpack.WebpackOptionsApply, readTo: () => webpack.config.WebpackOptionsApply },
34+
{ from: "defineConfig", to: "config.defineConfig", readFrom: () => webpack.defineConfig, readTo: () => webpack.config.defineConfig },
35+
{ from: "validateSchema", to: "config.validateSchema", readFrom: () => webpack.validateSchema, readTo: () => webpack.config.validateSchema },
36+
{ from: "ConcatenationScope", to: "optimize.ConcatenationScope", readFrom: () => webpack.ConcatenationScope, readTo: () => webpack.optimize.ConcatenationScope },
37+
{ from: "OptimizationStages", to: "optimize.OptimizationStages", readFrom: () => webpack.OptimizationStages, readTo: () => webpack.optimize.OptimizationStages },
38+
{ from: "RuntimeGlobals", to: "runtime.RuntimeGlobals", readFrom: () => webpack.RuntimeGlobals, readTo: () => webpack.runtime.RuntimeGlobals },
39+
{ from: "RuntimeModule", to: "runtime.RuntimeModule", readFrom: () => webpack.RuntimeModule, readTo: () => webpack.runtime.RuntimeModule },
40+
{ from: "AutomaticPrefetchPlugin", to: "prefetch.AutomaticPrefetchPlugin", readFrom: () => webpack.AutomaticPrefetchPlugin, readTo: () => webpack.prefetch.AutomaticPrefetchPlugin },
41+
{ from: "PrefetchPlugin", to: "prefetch.PrefetchPlugin", readFrom: () => webpack.PrefetchPlugin, readTo: () => webpack.prefetch.PrefetchPlugin },
42+
{ from: "web.CssLoadingRuntimeModule", to: "css.CssLoadingRuntimeModule", readFrom: () => webpack.web.CssLoadingRuntimeModule, readTo: () => webpack.css.CssLoadingRuntimeModule }
43+
];
44+
45+
describe("scoped exports", () => {
46+
for (const { name, read } of SCOPED) {
47+
it(`should expose webpack.${name}`, () => {
48+
expect(read()).toBeDefined();
49+
});
50+
}
51+
52+
for (const { from, to, readFrom, readTo } of KEPT_ALIASES) {
53+
it(`should keep webpack.${from} pointing at webpack.${to}`, () => {
54+
expect(readFrom()).toBe(readTo());
55+
});
56+
}
57+
58+
it("should keep the lib root shim pointing at util.RequestShortener", () => {
59+
expect(require("../../lib/RequestShortener")).toBe(
60+
webpack.util.RequestShortener
61+
);
62+
});
63+
});

0 commit comments

Comments
 (0)