feat: add appendRules util to tools.rspack config (#3755)

Co-authored-by: neverland <[email protected]>

packages/core/src/provider/rspackConfig.ts

@@ -63,6 +63,17 @@ export async function getConfigUtils(
       config.module.rules.unshift(...ruleArr);
     },
 
+    appendRules(rules) {
+      const ruleArr = castArray(rules);
+      if (!config.module) {
+        config.module = {};
+      }
+      if (!config.module.rules) {
+        config.module.rules = [];
+      }
+      config.module.rules.push(...ruleArr);
+    },
+
     prependPlugins(plugins) {
       const pluginArr = castArray(plugins);
       if (!config.plugins) {

packages/core/src/types/config.ts

@@ -76,6 +76,7 @@ export type ToolsHtmlPluginConfig = ConfigChainWithContext<
 
 export type ModifyRspackConfigUtils = ModifyChainUtils & {
   addRules: (rules: RspackRule | RspackRule[]) => void;
+  appendRules: (rules: RspackRule | RspackRule[]) => void;
   prependPlugins: (
     plugins: BundlerPluginInstance | BundlerPluginInstance[],
   ) => void;

packages/core/src/types/plugin.ts

@@ -90,6 +90,7 @@ export type ModifyWebpackChainUtils = ModifyChainUtils & {
 
 export type ModifyWebpackConfigUtils = ModifyWebpackChainUtils & {
   addRules: (rules: RuleSetRule | RuleSetRule[]) => void;
+  appendRules: (rules: RuleSetRule | RuleSetRule[]) => void;
   prependPlugins: (
     plugins: WebpackPluginInstance | WebpackPluginInstance[],
   ) => void;

packages/core/tests/__snapshots__/default.test.ts.snap

@@ -1440,6 +1440,10 @@ exports[`tools.rspack > should match snapshot 1`] = `
         "test": /\\\\\\.wasm\\$/,
         "type": "asset/resource",
       },
+      {
+        "loader": "foo-loader",
+        "test": /\\\\\\.foo/,
+      },
     ],
   },
   "name": "web",

packages/core/tests/default.test.ts

@@ -58,7 +58,7 @@ describe('tools.rspack', () => {
     const rsbuild = await createStubRsbuild({
       rsbuildConfig: {
         tools: {
-          rspack: (_config, { addRules, prependPlugins }) => {
+          rspack: (_config, { addRules, prependPlugins, appendRules }) => {
             addRules({
               test: /\.test$/,
               use: [
@@ -67,6 +67,11 @@ describe('tools.rspack', () => {
                 },
               ],
             });
+            appendRules({
+              test: /\.foo/,
+              loader: 'foo-loader',
+            });
+
             prependPlugins([new TestPlugin()]);
           },
         },

website/docs/en/config/tools/rspack.mdx

@@ -235,7 +235,9 @@ export default {
 
 - **Type:** `(rules: RuleSetRule | RuleSetRule[]) => void`
 
-Add additional [Rspack rules](https://rspack.dev/config/module#modulerules).
+Add additional [Rspack rules](https://rspack.dev/config/module#modulerules) to the head of the internal Rspack module rules array.
+
+It should be noted that Rspack loaders will be executed in right-to-left order. If you want the loader you added to be executed before other loaders (Normal Phase), you should use [appendRules](#appendrules) to add the rule to the end.
 
 For example:
 
@@ -265,9 +267,39 @@ export default {
 };
 ```
 
-:::tip
-The `addRules(...)` method will prepend rules to Rspack rule list. To append rules, use `config.module.rules.push(...)` instead.
-:::
+### appendRules
+
+- **Type:** `(rules: RuleSetRule | RuleSetRule[]) => void`
+
+Add additional [Rspack rules](https://rspack.dev/config/module#modulerules) to the end of the internal Rspack module rules array.
+
+For example:
+
+```ts
+export default {
+  tools: {
+    rspack: (config, { appendRules }) => {
+      // add a single rule
+      appendRules({
+        test: /\.foo/,
+        loader: require.resolve('foo-loader'),
+      });
+
+      // Add multiple rules as an array
+      appendRules([
+        {
+          test: /\.foo/,
+          loader: require.resolve('foo-loader'),
+        },
+        {
+          test: /\.bar/,
+          loader: require.resolve('bar-loader'),
+        },
+      ]);
+    },
+  },
+};
+```
 
 ### prependPlugins
 

website/docs/zh/config/tools/rspack.mdx

@@ -235,7 +235,9 @@ export default {
 
 - **类型：** `(rules: RuleSetRule | RuleSetRule[]) => void`
 
-添加额外的 [Rspack rules](https://rspack.dev/config/module#modulerules)。
+添加额外的 [Rspack rules](https://rspack.dev/config/module#modulerules) 到 Rspack rules 列表的最前面。
+
+需要注意的是，Rspack loaders 会按照从右到左的顺序执行，如果你希望你添加的 loader（Normal Phase）先于其他 loader 执行，应使用 [appendRules](#appendrules) 将该规则添加到最后面。
 
 示例：
 
@@ -265,9 +267,39 @@ export default {
 };
 ```
 
-:::tip
-`addRules(...)` 会将新规则插入到 Rspack rules 列表的最前面。如果想要在末尾插入新规则，请改用 `config.module.rules.push(...)`。
-:::
+### appendRules
+
+- **类型：** `(rules: RuleSetRule | RuleSetRule[]) => void`
+
+添加额外的 [Rspack rules](https://rspack.dev/config/module#modulerules) 到 Rspack rules 列表的最后面。
+
+示例：
+
+```ts
+export default {
+  tools: {
+    rspack: (config, { appendRules }) => {
+      // 追加单条规则
+      appendRules({
+        test: /\.foo/,
+        loader: require.resolve('foo-loader'),
+      });
+
+      // 以数组形式追加多条规则
+      appendRules([
+        {
+          test: /\.foo/,
+          loader: require.resolve('foo-loader'),
+        },
+        {
+          test: /\.bar/,
+          loader: require.resolve('bar-loader'),
+        },
+      ]);
+    },
+  },
+};
+```
 
 ### prependPlugins