feat: improve deprecation warning messages (#12524)

chenjiahan · web-flow · commit 9c26ab04d675 · 2025-12-23T13:03:01.000+08:00
* feat: improve deprecation warning messages

* fix: comment

* fix: proxy
diff --git a/packages/rspack-test-tools/src/helper/legacy/deprecationTracking.js b/packages/rspack-test-tools/src/helper/legacy/deprecationTracking.js
@@ -6,26 +6,18 @@
 
 "use strict";
 
-const util = require("util");
-
 let interception = undefined;
 
-const originalDeprecate = util.deprecate;
-util.deprecate = (fn, message, code) => {
-	const original = originalDeprecate(fn, message, code);
+const originalWarn = console.warn;
 
-	return function (...args) {
-		if (interception) {
-			interception.set(`${code}: ${message}`, {
-				code,
-				message,
-				stack: new Error(message).stack
-			});
-			return fn.apply(this, args);
-		} else {
-			return original.apply(this, args);
-		}
-	};
+console.warn = (message, ...args) => {
+	if (interception && typeof message === 'string' && message.includes('[Rspack Deprecation]')) {
+		interception.set(message, {
+			message,
+			stack: new Error(message).stack
+		});
+	}
+	return originalWarn.apply(console, [message, ...args]);
 };
 
 exports.start = handler => {
diff --git a/packages/rspack/src/builtin-plugin/lazy-compilation/middleware.ts b/packages/rspack/src/builtin-plugin/lazy-compilation/middleware.ts
@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { type Compiler, MultiCompiler } from "../..";
 import type { LazyCompilationOptions } from "../../config";
 import type { MiddlewareHandler } from "../../config/devServer";
+import { deprecate } from "../../util";
 import { BuiltinLazyCompilationPlugin } from "./lazyCompilation";
 
 export const LAZY_COMPILATION_PREFIX = "/lazy-compilation-using-";
@@ -57,28 +58,25 @@ export const lazyCompilationMiddleware = (
 		const middlewareByCompiler: Map<string, MiddlewareHandler> = new Map();
 
 		let i = 0;
-		let isReportDeprecatedWarned = false;
-		let isReportRepeatWarned = false;
+
 		for (const c of compiler.compilers) {
 			if (c.options.experiments.lazyCompilation) {
 				if (c.name) {
-					console.warn(
+					deprecate(
 						`The 'experiments.lazyCompilation' option in compiler named '${c.name}' is deprecated, please use the Configuration top level 'lazyCompilation' instead.`
 					);
-				} else if (!isReportDeprecatedWarned) {
-					console.warn(DEPRECATED_LAZY_COMPILATION_OPTIONS_WARN);
-					isReportDeprecatedWarned = true;
+				} else {
+					deprecate(DEPRECATED_LAZY_COMPILATION_OPTIONS_WARN);
 				}
 			}
 
 			if (c.options.lazyCompilation && c.options.experiments.lazyCompilation) {
 				if (c.name) {
-					console.warn(
+					deprecate(
 						`The top-level 'lazyCompilation' option in compiler named '${c.name}' will override the 'experiments.lazyCompilation' option.`
 					);
-				} else if (!isReportRepeatWarned) {
-					console.warn(REPEAT_LAZY_COMPILATION_OPTIONS_WARN);
-					isReportRepeatWarned = true;
+				} else {
+					deprecate(REPEAT_LAZY_COMPILATION_OPTIONS_WARN);
 				}
 			}
 
@@ -125,9 +123,9 @@ export const lazyCompilationMiddleware = (
 	}
 
 	if (compiler.options.experiments.lazyCompilation) {
-		console.warn(DEPRECATED_LAZY_COMPILATION_OPTIONS_WARN);
+		deprecate(DEPRECATED_LAZY_COMPILATION_OPTIONS_WARN);
 		if (compiler.options.lazyCompilation) {
-			console.warn(REPEAT_LAZY_COMPILATION_OPTIONS_WARN);
+			deprecate(REPEAT_LAZY_COMPILATION_OPTIONS_WARN);
 		}
 	}
 
diff --git a/packages/rspack/src/config/normalization.ts b/packages/rspack/src/config/normalization.ts
@@ -9,10 +9,10 @@
  */
 
 import path from "node:path";
-import util from "node:util";
 import type { HttpUriPluginOptions } from "../builtin-plugin";
 import type { Compilation } from "../Compilation";
 import type WebpackError from "../lib/WebpackError";
+import { deprecate } from "../util";
 import type {
 	Amd,
 	AssetModuleFilename,
@@ -153,10 +153,9 @@ export const getNormalizedRspackOptions = (
 					: getNormalizedEntryStatic(config.entry),
 		output: nestedConfig(config.output, output => {
 			if ("cssHeadDataCompression" in output) {
-				util.deprecate(
-					() => {},
+				deprecate(
 					"cssHeadDataCompression is not used now, see https://github.com/web-infra-dev/rspack/pull/8534, this option could be removed in the future"
-				)();
+				);
 			}
 
 			const { library } = output;
@@ -349,40 +348,34 @@ export const getNormalizedRspackOptions = (
 		plugins: nestedArray(config.plugins, p => [...p]),
 		experiments: nestedConfig(config.experiments, experiments => {
 			if (experiments.layers) {
-				util.deprecate(
-					() => {},
-					"`experiments.layers` config has been deprecated and will be removed in Rspack v2.0. Feature layers will be always enabled. Please remove this option from your Rspack configuration."
-				)();
+				deprecate(
+					"`experiments.layers` config is deprecated and will be removed in Rspack v2.0. Feature layers will always be enabled. Remove this option from your Rspack configuration."
+				);
 			}
 			if (experiments.topLevelAwait === false) {
-				util.deprecate(
-					() => {},
-					"`experiments.topLevelAwait` config has been deprecated and will be removed in Rspack v2.0. Top-level await will be always enabled. Please remove this option from your Rspack configuration."
-				)();
+				deprecate(
+					"`experiments.topLevelAwait` config is deprecated and will be removed in Rspack v2.0. Top-level await will always be enabled. Remove this option from your Rspack configuration."
+				);
 			}
 			if (experiments.lazyBarrel) {
-				util.deprecate(
-					() => {},
-					"`experiments.lazyBarrel` config has been deprecated and will be removed in Rspack v2.0. Lazy barrel is already stable and enabled by default. Please remove this option from your Rspack configuration."
-				)();
+				deprecate(
+					"`experiments.lazyBarrel` config is deprecated and will be removed in Rspack v2.0. Lazy barrel is already stable and enabled by default. Remove this option from your Rspack configuration."
+				);
 			}
 			if (experiments.inlineConst) {
-				util.deprecate(
-					() => {},
-					"`experiments.inlineConst` config has been deprecated and will be removed in Rspack v2.0. Inline Const is already stable and enabled by default. Please remove this option from your Rspack configuration."
-				)();
+				deprecate(
+					"`experiments.inlineConst` config is deprecated and will be removed in Rspack v2.0. Inline Const is already stable and enabled by default. Remove this option from your Rspack configuration."
+				);
 			}
 			if (experiments.inlineEnum) {
-				util.deprecate(
-					() => {},
-					"`experiments.inlineEnum` config has been deprecated and will be removed in Rspack v2.0. Inline Enum is already stable. Please remove this option from your Rspack configuration."
-				)();
+				deprecate(
+					"`experiments.inlineEnum` config is deprecated and will be removed in Rspack v2.0. Inline Enum is already stable. Remove this option from your Rspack configuration."
+				);
 			}
 			if (experiments.typeReexportsPresence) {
-				util.deprecate(
-					() => {},
-					"`experiments.typeReexportsPresence` config has been deprecated and will be removed in Rspack v2.0. typeReexportsPresence is already stable. Please remove this option from your Rspack configuration."
-				)();
+				deprecate(
+					"`experiments.typeReexportsPresence` config is deprecated and will be removed in Rspack v2.0. typeReexportsPresence is already stable. Remove this option from your Rspack configuration."
+				);
 			}
 			return {
 				...experiments,
diff --git a/packages/rspack/src/config/types.ts b/packages/rspack/src/config/types.ts
@@ -2789,6 +2789,7 @@ export type Experiments = {
 	outputModule?: boolean;
 	/**
 	 * Enable top-level await.
+	 * @deprecated This option is deprecated, top-level await is enabled by default.
 	 * @default true
 	 */
 	topLevelAwait?: boolean;
diff --git a/packages/rspack/src/rspack.ts b/packages/rspack/src/rspack.ts
@@ -7,7 +7,6 @@
  * Copyright (c) JS Foundation and other contributors
  * https://github.com/webpack/webpack/blob/main/LICENSE
  */
-import util from "node:util";
 import type { Callback } from "@rspack/lite-tapable";
 import { Compiler } from "./Compiler";
 import {
@@ -26,7 +25,7 @@ import MultiStats from "./MultiStats";
 import NodeEnvironmentPlugin from "./node/NodeEnvironmentPlugin";
 import { RspackOptionsApply } from "./rspackOptionsApply";
 import { Stats } from "./Stats";
-import { isNil } from "./util";
+import { deprecate, isNil } from "./util";
 import { validateRspackConfig } from "./util/validateConfig";
 
 function createMultiCompiler(options: MultiRspackOptions): MultiCompiler {
@@ -153,10 +152,9 @@ function rspack(
 	} else {
 		const { compiler, watch } = create();
 		if (watch) {
-			util.deprecate(
-				() => {},
+			deprecate(
 				"A 'callback' argument needs to be provided to the 'rspack(options, callback)' function when the 'watch' option is set. There is no way to handle the 'watch' option without a callback."
-			)();
+			);
 		}
 		return compiler;
 	}
diff --git a/packages/rspack/src/util/index.ts b/packages/rspack/src/util/index.ts
@@ -60,9 +60,21 @@ export function stringifyLoaderObject(o: LoaderObject): string {
 }
 
 export const unsupported = (name: string, issue?: string) => {
-	let s = `${name} is not supported by rspack.`;
+	let s = `${name} is not supported by Rspack.`;
 	if (issue) {
-		s += ` Please refer to issue ${issue} for more information.`;
+		s += ` Refer to issue ${issue} for more information.`;
 	}
 	throw new Error(s);
 };
+
+const warnedMessages = new Set<string>();
+
+export function deprecate(message: string): void {
+	// ensure we only warn once per message
+	if (warnedMessages.has(message)) {
+		return;
+	}
+
+	warnedMessages.add(message);
+	console.warn(`[Rspack Deprecation] ${message}`);
+}
