Skip to content

Commit a3773f5

Browse files
feat: default experiments.css/html/asyncWebAssembly to "auto" (#21365)
* feat: default experiments css/html/asyncWebAssembly to "auto" Default `experiments.css`, `experiments.html` and `experiments.asyncWebAssembly` to `"auto"`, which enables the built-in module type unless the user already registers a loader (or explicit type) for those files — so enabling them by default does not break existing css-loader/html-loader/wasm-loader setups. Detection lives on `RuleSetCompiler.hasRuleForResource` (reusing `compileCondition`): it walks `module.rules` (including `oneOf`/`rules`), treats `include`/`exclude` leniently, ignores `enforce: "pre"|"post"` loaders, and also counts a `test` regexp that references the extension so filename-scoped loaders are detected. `asyncWebAssembly` "auto" defers to `syncWebAssembly`. Auto-enabled html/css stay below `.js` in the ESM resolve extensions (only an explicit opt-in keeps `.html` ahead of `.js`), and `devtool` is resolved after experiments so auto-enabled css still gets the default dev css source map. * fix(html): hoist HtmlModulesPlugin requires out of the compilation hook Enabling `experiments.html` by default applies HtmlModulesPlugin to every build. Its lazy `require`s inside the newCompilation hook crashed a watch rebuild that raced after Jest teardown; hoisting them to module scope fixes that and avoids re-requiring per compilation. Keep the no-loader Errors case opted out of the html experiment so it still exercises that path.
1 parent 2d60c44 commit a3773f5

27 files changed

Lines changed: 1354 additions & 823 deletions
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+
Default `experiments.css`, `experiments.html` and `experiments.asyncWebAssembly` to `"auto"`, enabling the built-in support unless a loader is registered for those files.

‎declarations/WebpackOptions.d.ts‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1335,10 +1335,10 @@ export interface LibraryCustomUmdObject {
13351335
*/
13361336
export interface Experiments {
13371337
/**
1338-
* Support WebAssembly as asynchronous EcmaScript Module.
1338+
* Support WebAssembly as asynchronous EcmaScript Module. `"auto"` (the default) enables it unless a loader is registered for WebAssembly files.
13391339
* @experimental
13401340
*/
1341-
asyncWebAssembly?: boolean;
1341+
asyncWebAssembly?: "auto" | boolean;
13421342
/**
13431343
* Enable backward-compat layer with deprecation warnings for many webpack 4 APIs.
13441344
* @experimental
@@ -1355,10 +1355,10 @@ export interface Experiments {
13551355
*/
13561356
cacheUnaffected?: boolean;
13571357
/**
1358-
* Enable css support.
1358+
* Enable css support. `"auto"` (the default) enables the built-in CSS support unless a loader is registered for CSS files.
13591359
* @experimental
13601360
*/
1361-
css?: boolean;
1361+
css?: "auto" | boolean;
13621362
/**
13631363
* Enable experimental tc39 proposal https://github.com/tc39/proposal-defer-import-eval. This allows to defer execution of a module until it's first use.
13641364
* @experimental
@@ -1370,10 +1370,10 @@ export interface Experiments {
13701370
*/
13711371
futureDefaults?: boolean;
13721372
/**
1373-
* Enable HTML entry support. Treats `.html` files as a first-class module type so they can be used directly as entry points.
1373+
* Enable HTML entry support. Treats `.html` files as a first-class module type so they can be used directly as entry points. `"auto"` (the default) enables it unless a loader is registered for HTML files.
13741374
* @experimental
13751375
*/
1376-
html?: boolean;
1376+
html?: "auto" | boolean;
13771377
/**
13781378
* Compile entrypoints and import()s only when they are accessed.
13791379
* @experimental
@@ -3547,10 +3547,10 @@ export interface EntryStaticNormalized {
35473547
*/
35483548
export interface ExperimentsNormalized {
35493549
/**
3550-
* Support WebAssembly as asynchronous EcmaScript Module.
3550+
* Support WebAssembly as asynchronous EcmaScript Module. `"auto"` (the default) enables it unless a loader is registered for WebAssembly files.
35513551
* @experimental
35523552
*/
3553-
asyncWebAssembly?: boolean;
3553+
asyncWebAssembly?: "auto" | boolean;
35543554
/**
35553555
* Enable backward-compat layer with deprecation warnings for many webpack 4 APIs.
35563556
* @experimental
@@ -3567,10 +3567,10 @@ export interface ExperimentsNormalized {
35673567
*/
35683568
cacheUnaffected?: boolean;
35693569
/**
3570-
* Enable css support.
3570+
* Enable css support. `"auto"` (the default) enables the built-in CSS support unless a loader is registered for CSS files.
35713571
* @experimental
35723572
*/
3573-
css?: boolean;
3573+
css?: "auto" | boolean;
35743574
/**
35753575
* Enable experimental tc39 proposal https://github.com/tc39/proposal-defer-import-eval. This allows to defer execution of a module until it's first use.
35763576
* @experimental
@@ -3582,10 +3582,10 @@ export interface ExperimentsNormalized {
35823582
*/
35833583
futureDefaults?: boolean;
35843584
/**
3585-
* Enable HTML entry support. Treats `.html` files as a first-class module type so they can be used directly as entry points.
3585+
* Enable HTML entry support. Treats `.html` files as a first-class module type so they can be used directly as entry points. `"auto"` (the default) enables it unless a loader is registered for HTML files.
35863586
* @experimental
35873587
*/
3588-
html?: boolean;
3588+
html?: "auto" | boolean;
35893589
/**
35903590
* Compile entrypoints and import()s only when they are accessed.
35913591
* @experimental

‎lib/config/defaults.js‎

Lines changed: 71 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ const {
3131
WEBASSEMBLY_MODULE_TYPE_SYNC
3232
} = require("../ModuleTypeConstants");
3333
const Template = require("../Template");
34+
const RuleSetCompiler = require("../rules/RuleSetCompiler");
3435
const { cleverMerge } = require("../util/cleverMerge");
3536
const {
3637
getDefaultTarget,
@@ -71,6 +72,7 @@ const {
7172
/** @typedef {import("../../declarations/WebpackOptions").ParserOptionsByModuleTypeKnown} ParserOptionsByModuleTypeKnown */
7273
/** @typedef {import("../../declarations/WebpackOptions").Performance} Performance */
7374
/** @typedef {import("../../declarations/WebpackOptions").ResolveOptions} ResolveOptions */
75+
/** @typedef {import("../../declarations/WebpackOptions").RuleSetRule} RuleSetRule */
7476
/** @typedef {import("../../declarations/WebpackOptions").RuleSetRules} RuleSetRules */
7577
/** @typedef {import("../../declarations/WebpackOptions").SnapshotOptions} SnapshotOptions */
7678
/** @typedef {import("../../declarations/WebpackOptions").WebpackOptionsNormalized} WebpackOptionsNormalized */
@@ -341,6 +343,26 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
341343
}
342344
}
343345

346+
D(options, "watch", false);
347+
D(options, "profile", false);
348+
D(options, "parallelism", 100);
349+
D(options, "recordsInputPath", false);
350+
D(options, "recordsOutputPath", false);
351+
352+
// Capture the raw html intent before "auto" is resolved: only an explicit
353+
// `html: true` (or futureDefaults) keeps `.html` ahead of `.js` when resolving.
354+
const htmlExplicitlyEnabled = options.experiments.html === true;
355+
const htmlWasUnset = options.experiments.html === undefined;
356+
357+
applyExperimentsDefaults(options.experiments, {
358+
production,
359+
development,
360+
targetProperties,
361+
rules: options.module.rules
362+
});
363+
364+
// After experiments are resolved: the default dev source map depends on the
365+
// (possibly "auto"-resolved) `experiments.css` value.
344366
F(
345367
options,
346368
"devtool",
@@ -363,22 +385,14 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
363385
)
364386
);
365387

366-
D(options, "watch", false);
367-
D(options, "profile", false);
368-
D(options, "parallelism", 100);
369-
D(options, "recordsInputPath", false);
370-
D(options, "recordsOutputPath", false);
371-
372-
applyExperimentsDefaults(options.experiments, {
373-
production,
374-
development,
375-
targetProperties
376-
});
377-
378388
const futureDefaults =
379389
/** @type {NonNullable<ExperimentsNormalized["futureDefaults"]>} */
380390
(options.experiments.futureDefaults);
381391

392+
// `.html` outranks `.js` only for an explicit opt-in (`html: true`, or the
393+
// futureDefaults-forced default), never for the auto-enabled default.
394+
const htmlFirst = htmlExplicitlyEnabled || (htmlWasUnset && futureDefaults);
395+
382396
F(options, "validate", () => !(futureDefaults === true && production));
383397

384398
// Progress lives on infrastructureLogging; webpack@6 shows the interactive
@@ -418,7 +432,7 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
418432
entry: options.entry,
419433
futureDefaults,
420434
asyncWebAssembly:
421-
/** @type {NonNullable<ExperimentsNormalized["asyncWebAssembly"]>} */
435+
/** @type {boolean} */
422436
(options.experiments.asyncWebAssembly)
423437
});
424438

@@ -434,13 +448,13 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
434448
/** @type {NonNullable<ExperimentsNormalized["syncWebAssembly"]>} */
435449
(options.experiments.syncWebAssembly),
436450
asyncWebAssembly:
437-
/** @type {NonNullable<ExperimentsNormalized["asyncWebAssembly"]>} */
451+
/** @type {boolean} */
438452
(options.experiments.asyncWebAssembly),
439453
css:
440-
/** @type {NonNullable<ExperimentsNormalized["css"]>} */
454+
/** @type {boolean} */
441455
(options.experiments.css),
442456
html:
443-
/** @type {NonNullable<ExperimentsNormalized["html"]>} */
457+
/** @type {boolean} */
444458
(options.experiments.html),
445459
typescript:
446460
/** @type {NonNullable<ExperimentsNormalized["typescript"]>} */
@@ -518,7 +532,7 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
518532
development,
519533
production,
520534
css:
521-
/** @type {NonNullable<ExperimentsNormalized["css"]>} */
535+
/** @type {boolean} */
522536
(options.experiments.css),
523537
records: Boolean(options.recordsInputPath || options.recordsOutputPath)
524538
});
@@ -530,11 +544,12 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
530544
targetProperties,
531545
mode: /** @type {Mode} */ (options.mode),
532546
css:
533-
/** @type {NonNullable<ExperimentsNormalized["css"]>} */
547+
/** @type {boolean} */
534548
(options.experiments.css),
535549
html:
536-
/** @type {NonNullable<ExperimentsNormalized["html"]>} */
550+
/** @type {boolean} */
537551
(options.experiments.html),
552+
htmlFirst,
538553
typescript:
539554
/** @type {NonNullable<ExperimentsNormalized["typescript"]>} */
540555
(options.experiments.typescript)
@@ -574,17 +589,22 @@ const applyWebpackOptionsDefaults = (options, compilerIndex) => {
574589
* @param {boolean} options.production is production
575590
* @param {boolean} options.development is development mode
576591
* @param {TargetProperties | false} options.targetProperties target properties
592+
* @param {RuleSetRules} options.rules user `module.rules`, used to resolve the css/html/asyncWebAssembly "auto" defaults
577593
* @returns {void}
578594
*/
579595
const applyExperimentsDefaults = (
580596
experiments,
581-
{ production, development, targetProperties }
597+
{ production, development, targetProperties, rules }
582598
) => {
583599
D(experiments, "futureDefaults", false);
584600
D(experiments, "backCompat", !experiments.futureDefaults);
585601
// TODO do we need sync web assembly in webpack@6?
586602
D(experiments, "syncWebAssembly", false);
587-
D(experiments, "asyncWebAssembly", experiments.futureDefaults);
603+
D(
604+
experiments,
605+
"asyncWebAssembly",
606+
experiments.futureDefaults ? true : "auto"
607+
);
588608
// the universal target (web + node, neither specific) only works as ESM
589609
const universal =
590610
Boolean(targetProperties) &&
@@ -603,12 +623,33 @@ const applyExperimentsDefaults = (
603623
D(experiments, "cacheUnaffected", experiments.futureDefaults);
604624
D(experiments, "deferImport", false);
605625
D(experiments, "sourceImport", false);
606-
F(experiments, "css", () => (experiments.futureDefaults ? true : undefined));
607-
F(experiments, "html", () => (experiments.futureDefaults ? true : undefined));
626+
F(experiments, "css", () => (experiments.futureDefaults ? true : "auto"));
627+
F(experiments, "html", () => (experiments.futureDefaults ? true : "auto"));
608628
F(experiments, "typescript", () =>
609629
experiments.futureDefaults ? true : undefined
610630
);
611631

632+
// Resolve the "auto" default: enable the built-in css/html module type unless
633+
// the user already registered a loader (or explicit type) for these files, so
634+
// enabling them by default does not break existing css-loader/html-loader setups.
635+
// The built-in `/\.css$/i` rule also covers `.module.css`, so a loader scoped to
636+
// CSS modules must disable the built-in type too — sample both extensions.
637+
if (experiments.css === "auto") {
638+
experiments.css = !(
639+
RuleSetCompiler.hasRuleForResource(rules, "/file.css") ||
640+
RuleSetCompiler.hasRuleForResource(rules, "/file.module.css")
641+
);
642+
}
643+
if (experiments.html === "auto") {
644+
experiments.html = !RuleSetCompiler.hasRuleForResource(rules, "/file.html");
645+
}
646+
// `syncWebAssembly` already claims `.wasm`, so don't let "auto" override it.
647+
if (experiments.asyncWebAssembly === "auto") {
648+
experiments.asyncWebAssembly =
649+
!experiments.syncWebAssembly &&
650+
!RuleSetCompiler.hasRuleForResource(rules, "/file.wasm");
651+
}
652+
612653
if (typeof experiments.buildHttp === "object") {
613654
D(experiments.buildHttp, "frozen", production);
614655
D(experiments.buildHttp, "upgrade", false);
@@ -2261,6 +2302,7 @@ const applyOptimizationDefaults = (
22612302
* @param {Mode} options.mode mode
22622303
* @param {boolean} options.css is css enabled
22632304
* @param {boolean} options.html is html enabled
2305+
* @param {boolean} options.htmlFirst whether `.html` should outrank `.js` when resolving (only when html was explicitly enabled)
22642306
* @param {boolean} options.typescript is typescript enabled
22652307
* @returns {ResolveOptions} resolve options
22662308
*/
@@ -2271,6 +2313,7 @@ const getResolveDefaults = ({
22712313
mode,
22722314
css,
22732315
html,
2316+
htmlFirst,
22742317
typescript
22752318
}) => {
22762319
/** @type {string[]} */
@@ -2292,10 +2335,13 @@ const getResolveDefaults = ({
22922335
? [".ts", ".js", ".json", ".wasm"]
22932336
: [".js", ".json", ".wasm"];
22942337

2295-
// HTML-first when enabled: `.html` outranks `.js`, `.css` is the last fallback.
2338+
// Explicitly enabling html keeps `.html` ahead of `.js` (html-as-entry feature).
2339+
// Auto-enabled html/css are lower-priority fallbacks after `.js`, so enabling
2340+
// them by default never makes `x.html`/`x.css` shadow `x.js`.
22962341
const esmResolveExtensions = [
2297-
...(html ? [".html"] : []),
2342+
...(html && htmlFirst ? [".html"] : []),
22982343
...jsExtensions,
2344+
...(html && !htmlFirst ? [".html"] : []),
22992345
...(css ? [".css"] : [])
23002346
];
23012347

‎lib/html/HtmlModulesPlugin.js‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,14 @@ const HtmlInlineStyleDependency = require("../dependencies/HtmlInlineStyleDepend
2020
const HtmlSourceDependency = require("../dependencies/HtmlSourceDependency");
2121
const StaticExportsDependency = require("../dependencies/StaticExportsDependency");
2222
const WebpackError = require("../errors/WebpackError");
23+
const JavascriptModulesPlugin = require("../javascript/JavascriptModulesPlugin");
2324
const { compareModulesByFullName } = require("../util/comparators");
2425
const createHash = require("../util/createHash");
26+
const { getUndoPath, makePathsRelative } = require("../util/identifier");
2527
const { digestNonNumericOnly } = require("../util/nonNumericOnlyHash");
28+
const {
29+
PUBLIC_PATH_AUTO: autoPlaceholder
30+
} = require("../util/publicPathPlaceholder");
2631
const removeBOM = require("../util/removeBOM");
2732
const HtmlGenerator = require("./HtmlGenerator");
2833
const HtmlModule = require("./HtmlModule");
@@ -555,13 +560,6 @@ class HtmlModulesPlugin {
555560
// template's `[contenthash]` placeholder works; the
556561
// compilation hash is also forwarded so `[fullhash]` /
557562
// `[hash]` work in user-supplied templates.
558-
const {
559-
getUndoPath,
560-
makePathsRelative
561-
} = require("../util/identifier");
562-
const {
563-
PUBLIC_PATH_AUTO: autoPlaceholder
564-
} = require("../util/publicPathPlaceholder");
565563

566564
// Sentinel-resolved content and its content hash depend only on
567565
// the HTML-type module source — not on the chunk or output
@@ -765,8 +763,6 @@ class HtmlModulesPlugin {
765763

766764
// Resolve sentinels at JS chunk render time so later passes
767765
// (SourceMapDevToolPlugin, size optimizers, RealContentHash) see resolved bytes.
768-
const JavascriptModulesPlugin = require("../javascript/JavascriptModulesPlugin");
769-
770766
const jsHooks =
771767
JavascriptModulesPlugin.getCompilationHooks(compilation);
772768
jsHooks.render.tap(PLUGIN_NAME, (source, renderContext) => {

0 commit comments

Comments
 (0)