feat: added CssModulesPlugin.getCompilationHooks(compilation).orderModules hook

alexander-akait · web-flow · commit 561ee9b5dd12 · 2026-05-19T15:49:56.000+03:00
diff --git a/.changeset/css-modules-order-name.md b/.changeset/css-modules-order-name.md
@@ -0,0 +1,5 @@
+---
+"webpack": minor
+---
+
+Add `CssModulesPlugin.getCompilationHooks(compilation).orderModules` hook. The hook is called once per CSS source type (CSS imports, CSS modules) with the chunk's modules pre-sorted by full module name; taps may return an ordered `Module[]` to override webpack's default import-order topological sort, or return `undefined` to keep the default. This lets a plugin enforce a deterministic CSS module order (e.g. by file path) and side-step the "Conflicting order between css ..." warning.
diff --git a/lib/css/CssModulesPlugin.js b/lib/css/CssModulesPlugin.js
@@ -5,7 +5,7 @@
 
 "use strict";
 
-const { SyncHook, SyncWaterfallHook } = require("tapable");
+const { SyncBailHook, SyncHook, SyncWaterfallHook } = require("tapable");
 const {
 	CachedSource,
 	ConcatSource,
@@ -93,6 +93,7 @@ const CssParser = require("./CssParser");
  * @typedef {object} CompilationHooks
  * @property {SyncWaterfallHook<[Source, Module, ChunkRenderContext]>} renderModulePackage
  * @property {SyncHook<[Chunk, Hash, ChunkHashContext]>} chunkHash
+ * @property {SyncBailHook<[Chunk, Module[], Compilation], Module[] | undefined | void>} orderModules called for each CSS source type (CSS_IMPORT_TYPE, CSS_TYPE) with the chunk's modules pre-sorted by full module name; return an ordered `Module[]` to override the default import-order topological sort, or return `undefined` to keep the default
  */
 
 /**
@@ -160,7 +161,8 @@ class CssModulesPlugin {
 					"module",
 					"renderContext"
 				]),
-				chunkHash: new SyncHook(["chunk", "hash", "context"])
+				chunkHash: new SyncHook(["chunk", "hash", "context"]),
+				orderModules: new SyncBailHook(["chunk", "modules", "compilation"])
 			};
 			compilationHooksMap.set(compilation, hooks);
 		}
@@ -869,24 +871,33 @@ class CssModulesPlugin {
 		/** @type {string | undefined} */
 		let charset;
 
+		const hooks = CssModulesPlugin.getCompilationHooks(compilation);
+
+		/**
+		 * @param {Iterable<Module> | undefined} iter modules pre-sorted by full module name
+		 * @returns {Module[]} ordered modules
+		 */
+		const orderModules = (iter) => {
+			const modules = iter ? [...iter] : [];
+			const result = hooks.orderModules.call(chunk, modules, compilation);
+			if (result !== undefined) return result;
+			return this.getModulesInOrder(chunk, modules, compilation);
+		};
+
 		return /** @type {CssModule[]} */ ([
-			...this.getModulesInOrder(
-				chunk,
+			...orderModules(
 				chunkGraph.getOrderedChunkModulesIterableBySourceType(
 					chunk,
 					CSS_IMPORT_TYPE,
 					compareModulesByFullName(compilation.compiler)
-				),
-				compilation
+				)
 			),
-			...this.getModulesInOrder(
-				chunk,
+			...orderModules(
 				chunkGraph.getOrderedChunkModulesIterableBySourceType(
 					chunk,
 					CSS_TYPE,
 					compareModulesByFullName(compilation.compiler)
-				),
-				compilation
+				)
 			).map((module) => {
 				if (
 					typeof (/** @type {BuildInfo} */ (module.buildInfo).charset) !==
diff --git a/test/configCases/css/css-modules-order-hook/a.css b/test/configCases/css/css-modules-order-hook/a.css
@@ -0,0 +1,3 @@
+body {
+	color: a;
+}
diff --git a/test/configCases/css/css-modules-order-hook/b.css b/test/configCases/css/css-modules-order-hook/b.css
@@ -0,0 +1,3 @@
+body {
+	color: b;
+}
diff --git a/test/configCases/css/css-modules-order-hook/c.css b/test/configCases/css/css-modules-order-hook/c.css
@@ -0,0 +1,3 @@
+body {
+	color: c;
+}
diff --git a/test/configCases/css/css-modules-order-hook/d.css b/test/configCases/css/css-modules-order-hook/d.css
@@ -0,0 +1,3 @@
+body {
+	color: d;
+}
diff --git a/test/configCases/css/css-modules-order-hook/e.css b/test/configCases/css/css-modules-order-hook/e.css
@@ -0,0 +1,3 @@
+body {
+	color: e;
+}
diff --git a/test/configCases/css/css-modules-order-hook/fallback.js b/test/configCases/css/css-modules-order-hook/fallback.js
@@ -0,0 +1,5 @@
+import { expectCssOrder } from "./helpers";
+
+it("orderModules: returning undefined falls back to the default import-order sort", done => {
+	expectCssOrder("fallback", 2, "bcdea123", done);
+});
diff --git a/test/configCases/css/css-modules-order-hook/helpers.js b/test/configCases/css/css-modules-order-hook/helpers.js
@@ -0,0 +1,26 @@
+import fs from "fs";
+import path from "path";
+
+export function expectCssOrder(variant, idx, expected, done) {
+	__non_webpack_require__(`./${variant}-lazy4_js.bundle${idx}.js`);
+	Promise.all([
+		import("./lazy1.css"),
+		import("./lazy2.css"),
+		import("./lazy3.css"),
+		import("./lazy4.js")
+	]).then(() => {
+		try {
+			const matches = fs
+				.readFileSync(
+					path.join(__dirname, `${variant}-css.bundle${idx}.css`),
+					"utf-8"
+				)
+				.match(/color: ([a-z0-9])/g)
+				.map(match => match[7]);
+			expect(matches).toEqual(expected.split(""));
+			done();
+		} catch (e) {
+			done(e);
+		}
+	}, done);
+}
diff --git a/test/configCases/css/css-modules-order-hook/lazy1.css b/test/configCases/css/css-modules-order-hook/lazy1.css
@@ -0,0 +1,7 @@
+@import "b.css";
+@import "c.css";
+@import "a.css";
+
+body {
+	color: 1;
+}
diff --git a/test/configCases/css/css-modules-order-hook/lazy2.css b/test/configCases/css/css-modules-order-hook/lazy2.css
@@ -0,0 +1,7 @@
+@import "c.css";
+@import "b.css";
+@import "a.css";
+
+body {
+	color: 2;
+}
diff --git a/test/configCases/css/css-modules-order-hook/lazy3.css b/test/configCases/css/css-modules-order-hook/lazy3.css
@@ -0,0 +1,6 @@
+@import "d.css";
+@import "a.css";
+
+body {
+	color: 3;
+}
diff --git a/test/configCases/css/css-modules-order-hook/lazy4.js b/test/configCases/css/css-modules-order-hook/lazy4.js
@@ -0,0 +1,2 @@
+import "./e.css";
+import "./a.css";
diff --git a/test/configCases/css/css-modules-order-hook/multi-tap.js b/test/configCases/css/css-modules-order-hook/multi-tap.js
@@ -0,0 +1,5 @@
+import { expectCssOrder } from "./helpers";
+
+it("orderModules: SyncBailHook short-circuits at the first tap that returns a value", done => {
+	expectCssOrder("multi-tap", 3, "abcde123", done);
+});
diff --git a/test/configCases/css/css-modules-order-hook/name.js b/test/configCases/css/css-modules-order-hook/name.js
@@ -0,0 +1,5 @@
+import { expectCssOrder } from "./helpers";
+
+it("orderModules: returning modules as-is yields name-sorted CSS without warnings", done => {
+	expectCssOrder("name", 0, "abcde123", done);
+});
diff --git a/test/configCases/css/css-modules-order-hook/priority.js b/test/configCases/css/css-modules-order-hook/priority.js
@@ -0,0 +1,5 @@
+import { expectCssOrder } from "./helpers";
+
+it("orderModules: a tap can pin a specific file (e.css) to the front", done => {
+	expectCssOrder("priority", 1, "eabcd123", done);
+});
diff --git a/test/configCases/css/css-modules-order-hook/test.config.js b/test/configCases/css/css-modules-order-hook/test.config.js
@@ -0,0 +1,14 @@
+"use strict";
+
+const variants = ["name", "priority", "fallback", "multi-tap"];
+
+module.exports = {
+	findBundle(i) {
+		const variant = variants[i];
+		return [
+			`${variant}-css.bundle${i}.js`,
+			`${variant}-lazy4_js.bundle${i}.js`,
+			`bundle${i}.js`
+		];
+	}
+};
diff --git a/test/configCases/css/css-modules-order-hook/warnings.js b/test/configCases/css/css-modules-order-hook/warnings.js
@@ -0,0 +1,9 @@
+"use strict";
+
+module.exports = [
+	[
+		// Only the "fallback" config (which returns undefined from orderModules)
+		// keeps the default topological merge and therefore emits this warning.
+		/Conflicting order between css \.\/b\.css and css \.\/c\.css\nCSS modules are imported in:\n {2}- css \.\/lazy1\.css\n {2}- css \.\/lazy2\.css/
+	]
+];
diff --git a/test/configCases/css/css-modules-order-hook/webpack.config.js b/test/configCases/css/css-modules-order-hook/webpack.config.js
@@ -0,0 +1,109 @@
+"use strict";
+
+/** @typedef {import("../../../../").Compiler} Compiler */
+/** @typedef {ReturnType<typeof import("../../../../").css.CssModulesPlugin.getCompilationHooks>} CssCompilationHooks */
+
+/**
+ * @typedef {object} Variant
+ * @property {string} name scenario name
+ * @property {(hooks: CssCompilationHooks) => void} tap registers taps on the orderModules hook
+ */
+
+const E_CSS_RE = /[\\/]e\.css$/;
+
+/** @type {Variant[]} */
+const variants = [
+	{
+		name: "name",
+		tap(hooks) {
+			// Modules arrive pre-sorted by full module name, so return as-is.
+			hooks.orderModules.tap("Name", (_chunk, modules) => modules);
+		}
+	},
+	{
+		name: "priority",
+		tap(hooks) {
+			hooks.orderModules.tap("Priority", (_chunk, modules) => {
+				// e.css must be first; remaining order is preserved (already by name).
+				const result = [...modules];
+				result.sort((a, b) => {
+					const aFirst = E_CSS_RE.test(a.identifier());
+					const bFirst = E_CSS_RE.test(b.identifier());
+					if (aFirst && !bFirst) return -1;
+					if (!aFirst && bFirst) return 1;
+					return 0;
+				});
+				return result;
+			});
+		}
+	},
+	{
+		name: "fallback",
+		tap(hooks) {
+			// Returning undefined lets webpack apply its default import-order
+			// topological sort (which still emits the "Conflicting order" warning).
+			hooks.orderModules.tap("Fallback", () => undefined);
+		}
+	},
+	{
+		name: "multi-tap",
+		tap(hooks) {
+			hooks.orderModules.tap("First", (_chunk, modules) => modules);
+			hooks.orderModules.tap("Second", () => {
+				throw new Error(
+					"second tap must not run when the first tap returned a value"
+				);
+			});
+		}
+	}
+];
+
+/**
+ * @param {Variant} variant scenario variant
+ * @returns {import("../../../../").WebpackPluginInstance} plugin instance
+ */
+const makePlugin = (variant) => ({
+	/**
+	 * @param {Compiler} compiler compiler
+	 */
+	apply(compiler) {
+		compiler.hooks.compilation.tap("OrderModulesTestPlugin", (compilation) => {
+			const CssModulesPlugin = compiler.webpack.css.CssModulesPlugin;
+			variant.tap(CssModulesPlugin.getCompilationHooks(compilation));
+		});
+	}
+});
+
+/** @type {import("../../../../").Configuration[]} */
+module.exports = variants.map((variant, idx) => ({
+	target: "web",
+	mode: "development",
+	entry: `./${variant.name}.js`,
+	output: {
+		filename: `bundle${idx}.js`,
+		chunkFilename: `${variant.name}-[name].bundle${idx}.js`,
+		cssChunkFilename: `${variant.name}-[name].bundle${idx}.css`
+	},
+	experiments: {
+		css: true
+	},
+	optimization: {
+		chunkIds: "named",
+		splitChunks: {
+			cacheGroups: {
+				css: {
+					type: "css/auto",
+					enforce: true,
+					name: "css"
+				}
+			}
+		}
+	},
+	plugins: [makePlugin(variant)],
+	externalsPresets: {
+		node: true
+	},
+	node: {
+		__dirname: false
+	}
+}));
diff --git a/types.d.ts b/types.d.ts
@@ -3893,6 +3893,14 @@ declare interface CompilationHooksCssModulesPlugin {
 		Source
 	>;
 	chunkHash: SyncHook<[Chunk, Hash, ChunkHashContext]>;
+
+	/**
+	 * called for each CSS source type (CSS_IMPORT_TYPE, CSS_TYPE) with the chunk's modules pre-sorted by full module name; return an ordered `Module[]` to override the default import-order topological sort, or return `undefined` to keep the default
+	 */
+	orderModules: SyncBailHook<
+		[Chunk, Module[], Compilation],
+		undefined | void | Module[]
+	>;
 }
 declare interface CompilationHooksJavascriptModulesPlugin {
 	renderModuleContent: SyncWaterfallHook<

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"webpack": minor
 +---
++
 +Add `CssModulesPlugin.getCompilationHooks(compilation).orderModules` hook. The hook is called once per CSS source type (CSS imports, CSS modules) with the chunk's modules pre-sorted by full module name; taps may return an ordered `Module[]` to override webpack's default import-order topological sort, or return `undefined` to keep the default. This lets a plugin enforce a deterministic CSS module order (e.g. by file path) and side-step the "Conflicting order between css ..." warning.