feat: add enforce option to api.transform (#5174)

Author: chenjiahan

e2e/cases/plugin-api/plugin-transform-enforce/index.test.ts

@@ -0,0 +1,14 @@
+import { build, rspackOnlyTest } from '@e2e/helper';
+import { expect } from '@playwright/test';
+
+rspackOnlyTest(
+  'should allow plugin to specify the execution order via `enforce`',
+  async () => {
+    const rsbuild = await build({
+      cwd: __dirname,
+    });
+
+    const indexJs = await rsbuild.getIndexFile();
+    expect(indexJs.content).toContain('with enforce: pre');
+  },
+);

e2e/cases/plugin-api/plugin-transform-enforce/myPlugin.ts

@@ -0,0 +1,14 @@
+import type { RsbuildPlugin } from '@rsbuild/core';
+
+export const myPlugin: RsbuildPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    api.transform({ test: /\.js$/ }, ({ code }) => {
+      return code.replace('__placeholder__', 'without enforce');
+    });
+
+    api.transform({ test: /\.js$/, enforce: 'pre' }, ({ code }) => {
+      return code.replace('__placeholder__', 'with enforce: pre');
+    });
+  },
+};

e2e/cases/plugin-api/plugin-transform-enforce/rsbuild.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@rsbuild/core';
+import { myPlugin } from './myPlugin';
+
+export default defineConfig({
+  plugins: [myPlugin],
+});

e2e/cases/plugin-api/plugin-transform-enforce/src/index.js

@@ -0,0 +1 @@
+console.log('__placeholder__');

packages/core/src/initPlugins.ts

@@ -295,6 +295,9 @@ export function initPluginAPI({
           if (descriptor.mimetype) {
             rule.mimetype(descriptor.mimetype);
           }
+          if (descriptor.enforce) {
+            rule.enforce(descriptor.enforce);
+          }
 
           const loaderName = descriptor.raw
             ? 'transformRawLoader.mjs'

packages/core/src/types/plugin.ts

@@ -378,6 +378,15 @@ export type TransformDescriptor = {
    * @see https://rspack.dev/config/module#rulemimetype
    */
   mimetype?: Rspack.RuleSetCondition;
+  /**
+   * Specifies the execution order of the transform function.
+   * - When specified as 'pre', the transform function will execute before other
+   * transform functions (or Rspack loaders).
+   * - When specified as 'post', the transform function will execute after other
+   * transform functions (or Rspack loaders).
+   * @see https://rspack.dev/config/module#ruleenforce
+   */
+  enforce?: 'pre' | 'post';
 };
 
 export type TransformHook = (

website/docs/en/plugins/dev/core.mdx

@@ -219,6 +219,7 @@ type TransformDescriptor = {
   issuerLayer?: string;
   with?: Record<string, RuleSetCondition>;
   mimetype?: RuleSetCondition;
+  enforce?: 'pre' | 'post';
 };
 ```
 
@@ -304,6 +305,16 @@ api.transform({ mimetype: 'text/javascript' }, ({ code }) => {
 });
 ```
 
+- `enforce`: Specifies the execution order of the transform function, the same as Rspack's [Rule.enforce](https://rspack.dev/config/module#ruleenforce).
+  - When `enforce` is `pre`, the transform function will be executed before other transform functions (or Rspack loaders).
+  - When `enforce` is `post`, the transform function will be executed after other transform functions (or Rspack loaders).
+
+```js
+api.transform({ test: /\.md$/, enforce: 'pre' }, ({ code }) => {
+  // ...
+});
+```
+
 ### Handler param
 
 The handler param is a transformation function that takes the current module code and returns the transformed code.

website/docs/zh/plugins/dev/core.mdx

@@ -217,6 +217,7 @@ type TransformDescriptor = {
   issuerLayer?: string;
   with?: Record<string, RuleSetCondition>;
   mimetype?: RuleSetCondition;
+  enforce?: 'pre' | 'post';
 };
 ```
 
@@ -302,6 +303,16 @@ api.transform({ mimetype: 'text/javascript' }, ({ code }) => {
 });
 ```
 
+- `enforce`：指定 transform 函数的执行顺序，等同于 Rspack 的 [Rule.enforce](https://rspack.dev/zh/config/module#ruleenforce)。
+  - 当 `enforce` 为 `pre` 时，transform 函数会在其他 transform 函数（或 Rspack loader）之前执行。
+  - 当 `enforce` 为 `post` 时，transform 函数会在其他 transform 函数（或 Rspack loader）之后执行。
+
+```js
+api.transform({ test: /\.md$/, enforce: 'pre' }, ({ code }) => {
+  // ...
+});
+```
+
 ### handler 参数
 
 handler 参数是一个转换函数，接收模块当前的代码，并返回转换后的代码。