chore: gracefully explain unsupported interfaces (#12782)

martinjlowm · claude · hardfist · web-flow · commit 758f6227be24 · 2026-02-03T14:47:22.000+08:00
* feat(core): add helpful error messages for unsupported webpack hooks

When webpack plugins try to access hooks that don't exist in rspack,
provide a clear error message instead of the cryptic "Cannot read
properties of undefined (reading 'tap')".

The error message explains:
- Which hook is not supported
- That this typically happens with webpack plugins
- Lists all available hooks for reference

This helps developers quickly identify webpack compatibility issues.

* chore: add regression test on messaging unsupported hooks

* chore: update snapshot

---------

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
Co-authored-by: hardfist &lt;yangjianzju@gmail.com&gt;
diff --git a/packages/rspack/src/Compilation.ts b/packages/rspack/src/Compilation.ts
@@ -389,6 +389,26 @@ BREAKING CHANGE: Asset processing hooks in Compilation has been merged into a si
       afterSeal: new liteTapable.AsyncSeriesHook([]),
       needAdditionalPass: new liteTapable.SyncBailHook([]),
     };
+
+    // Wrap hooks with a Proxy to provide helpful error messages when
+    // webpack plugins try to access hooks that don't exist in rspack
+    const availableHooks = Object.keys(this.hooks);
+    this.hooks = new Proxy(this.hooks, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (value === undefined && typeof prop === 'string') {
+          const hooksList = availableHooks.join(', ');
+          throw new Error(
+            `Compilation.hooks.${prop} is not supported in rspack. ` +
+              `This typically happens when using webpack plugins that rely on webpack-specific hooks. ` +
+              `Consider using an rspack-compatible alternative or removing the incompatible plugin.\n\n` +
+              `Available compilation hooks: ${hooksList}`,
+          );
+        }
+        return value;
+      },
+    });
+
     this.compiler = compiler;
     this.resolverFactory = compiler.resolverFactory;
     this.inputFileSystem = compiler.inputFileSystem;
diff --git a/packages/rspack/src/Compiler.ts b/packages/rspack/src/Compiler.ts
@@ -260,6 +260,25 @@ class Compiler {
       additionalPass: new liteTapable.AsyncSeriesHook([]),
     };
 
+    // Wrap hooks with a Proxy to provide helpful error messages when
+    // webpack plugins try to access hooks that don't exist in rspack
+    const availableCompilerHooks = Object.keys(this.hooks);
+    this.hooks = new Proxy(this.hooks, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (value === undefined && typeof prop === 'string') {
+          const hooksList = availableCompilerHooks.join(', ');
+          throw new Error(
+            `Compiler.hooks.${prop} is not supported in rspack. ` +
+              `This typically happens when using webpack plugins that rely on webpack-specific hooks. ` +
+              `Consider using an rspack-compatible alternative or removing the incompatible plugin.\n\n` +
+              `Available compiler hooks: ${hooksList}`,
+          );
+        }
+        return value;
+      },
+    });
+
     const compilerRuntimeGlobals = createCompilerRuntimeGlobals(options);
     const compilerFn = function (...params: Parameters<typeof rspackFn>) {
       return rspackFn(...params);
diff --git a/tests/rspack-test/hookCases/compilation#unsupportedHookError/basic/output.snap.txt b/tests/rspack-test/hookCases/compilation#unsupportedHookError/basic/output.snap.txt
@@ -0,0 +1,40 @@
+```js title=main.js
+(() => {
+var __webpack_modules__ = ({
+402(module) {
+module.exports = "This is hook"
+
+
+},
+
+});
+// The module cache
+var __webpack_module_cache__ = {};
+
+// The require function
+function __webpack_require__(moduleId) {
+
+// Check if module is in cache
+var cachedModule = __webpack_module_cache__[moduleId];
+if (cachedModule !== undefined) {
+return cachedModule.exports;
+}
+// Create a new module (and put it into the cache)
+var module = (__webpack_module_cache__[moduleId] = {
+exports: {}
+});
+// Execute the module function
+__webpack_modules__[moduleId](module, module.exports, __webpack_require__);
+
+// Return the exports of the module
+return module.exports;
+
+}
+
+// startup
+// Load entry module and return exports
+// This entry module is referenced by other modules so it can't be inlined
+var __webpack_exports__ = __webpack_require__(402);
+})()
+;
+```
diff --git a/tests/rspack-test/hookCases/compilation#unsupportedHookError/basic/test.js b/tests/rspack-test/hookCases/compilation#unsupportedHookError/basic/test.js
@@ -0,0 +1,29 @@
+/** @type {import("@rspack/test-tools").THookCaseConfig} */
+module.exports = {
+	description: "should throw helpful error for unsupported compilation hooks",
+	options() {
+		return {
+			plugins: [
+				{
+					apply(compiler) {
+						compiler.hooks.compilation.tap("test", compilation => {
+							// Test accessing an unsupported hook that exists in webpack but not rspack
+							expect(() => {
+								compilation.hooks.nonExistentWebpackHook.tap("test", () => {});
+							}).toThrow(/Compilation\.hooks\.nonExistentWebpackHook is not supported in rspack/);
+
+							// Verify the error message includes the available hooks list
+							try {
+								compilation.hooks.nonExistentWebpackHook;
+							} catch (e) {
+								expect(e.message).toContain("Available compilation hooks:");
+								expect(e.message).toContain("processAssets");
+								expect(e.message).toContain("seal");
+							}
+						});
+					}
+				}
+			]
+		};
+	}
+};
diff --git a/tests/rspack-test/hookCases/compiler#unsupportedHookError/basic/output.snap.txt b/tests/rspack-test/hookCases/compiler#unsupportedHookError/basic/output.snap.txt
@@ -0,0 +1,40 @@
+```js title=main.js
+(() => {
+var __webpack_modules__ = ({
+402(module) {
+module.exports = "This is hook"
+
+
+},
+
+});
+// The module cache
+var __webpack_module_cache__ = {};
+
+// The require function
+function __webpack_require__(moduleId) {
+
+// Check if module is in cache
+var cachedModule = __webpack_module_cache__[moduleId];
+if (cachedModule !== undefined) {
+return cachedModule.exports;
+}
+// Create a new module (and put it into the cache)
+var module = (__webpack_module_cache__[moduleId] = {
+exports: {}
+});
+// Execute the module function
+__webpack_modules__[moduleId](module, module.exports, __webpack_require__);
+
+// Return the exports of the module
+return module.exports;
+
+}
+
+// startup
+// Load entry module and return exports
+// This entry module is referenced by other modules so it can't be inlined
+var __webpack_exports__ = __webpack_require__(402);
+})()
+;
+```
diff --git a/tests/rspack-test/hookCases/compiler#unsupportedHookError/basic/test.js b/tests/rspack-test/hookCases/compiler#unsupportedHookError/basic/test.js
@@ -0,0 +1,27 @@
+/** @type {import("@rspack/test-tools").THookCaseConfig} */
+module.exports = {
+	description: "should throw helpful error for unsupported compiler hooks",
+	options() {
+		return {
+			plugins: [
+				{
+					apply(compiler) {
+						// Test accessing an unsupported hook that exists in webpack but not rspack
+						expect(() => {
+							compiler.hooks.nonExistentWebpackHook.tap("test", () => {});
+						}).toThrow(/Compiler\.hooks\.nonExistentWebpackHook is not supported in rspack/);
+
+						// Verify the error message includes the available hooks list
+						try {
+							compiler.hooks.nonExistentWebpackHook;
+						} catch (e) {
+							expect(e.message).toContain("Available compiler hooks:");
+							expect(e.message).toContain("compilation");
+							expect(e.message).toContain("emit");
+						}
+					}
+				}
+			]
+		};
+	}
+};
