feat: add environments as a filter of api.transform (#2947)

e2e/cases/plugin-api/plugin-transform-by-environments/index.test.ts

@@ -0,0 +1,23 @@
+import { build } from '@e2e/helper';
+import { expect, test } from '@playwright/test';
+
+test('should allow plugin to transform code by targets', async () => {
+  const rsbuild = await build({
+    cwd: __dirname,
+  });
+
+  const files = await rsbuild.unwrapOutputJSON();
+  const webJs = Object.keys(files).find(
+    (file) =>
+      file.includes('index') &&
+      !file.includes('server') &&
+      file.endsWith('.js'),
+  );
+  const nodeJs = Object.keys(files).find(
+    (file) =>
+      file.includes('index') && file.includes('server') && file.endsWith('.js'),
+  );
+
+  expect(files[webJs!].includes('target is web')).toBeTruthy();
+  expect(files[nodeJs!].includes('target is node')).toBeTruthy();
+});

e2e/cases/plugin-api/plugin-transform-by-environments/myPlugin.ts

@@ -0,0 +1,17 @@
+import type { RsbuildPlugin } from '@rsbuild/core';
+
+export const myPlugin: RsbuildPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    api.transform({ test: /\.js$/, environments: ['web'] }, ({ code }) => {
+      return {
+        code: code.replace('hello', 'target is web'),
+      };
+    });
+    api.transform({ test: /\.js$/, environments: ['node'] }, ({ code }) => {
+      return {
+        code: code.replace('hello', 'target is node'),
+      };
+    });
+  },
+};

e2e/cases/plugin-api/plugin-transform-by-environments/rsbuild.config.ts

@@ -0,0 +1,20 @@
+import { myPlugin } from './myPlugin';
+
+export default {
+  plugins: [myPlugin],
+  environments: {
+    web: {
+      output: {
+        target: 'web',
+      },
+    },
+    node: {
+      output: {
+        target: 'node',
+        distPath: {
+          root: 'dist/server',
+        },
+      },
+    },
+  },
+};

e2e/cases/plugin-api/plugin-transform-by-environments/src/index.js

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

packages/core/src/initPlugins.ts

@@ -118,11 +118,20 @@ export function getPluginAPI({
 
     transformer[id] = handler;
 
-    hooks.modifyBundlerChain.tap((chain, { target }) => {
+    hooks.modifyBundlerChain.tap((chain, { target, environment }) => {
+      // filter by targets
       if (descriptor.targets && !descriptor.targets.includes(target)) {
         return;
       }
 
+      // filter by environments
+      if (
+        descriptor.environments &&
+        !descriptor.environments.includes(environment.name)
+      ) {
+        return;
+      }
+
       const rule = chain.module.rule(id);
 
       if (descriptor.test) {

packages/core/src/types/plugin.ts

@@ -221,6 +221,11 @@ export type TransformDescriptor = {
    * @see https://rsbuild.dev/config/output/targets
    */
   targets?: RsbuildTarget[];
+  /**
+   * Match based on the Rsbuild environment names and only apply the transform to certain environments.
+   * @see https://rsbuild.dev/config/environments
+   */
+  environments?: string[];
   /**
    * If raw is `true`, the transform handler will receive the Buffer type code instead of the string type.
    * @see https://rspack.dev/api/loader-api#raw-loader

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

@@ -170,7 +170,7 @@ Used to transform the code of modules.
 
 ```ts
 function Transform(
-  descriptor: { test?: RuleSetCondition | undefined },
+  descriptor: TransformDescriptor,
   handler: TransformHandler,
 ): void;
 ```
@@ -208,6 +208,7 @@ The descriptor param is an object describing the module's matching conditions.
 type TransformDescriptor = {
   test?: RuleSetCondition;
   targets?: RsbuildTarget[];
+  environments?: string[];
   resourceQuery?: RuleSetCondition;
   raw?: boolean;
 };
@@ -231,6 +232,14 @@ api.transform({ test: /\.pug$/, targets: ['web'] }, ({ code }) => {
 });
 ```
 
+- `environments`: matches the Rsbuild [environment](/guide/advanced/environments) name, and applies the current transform function only to the matched environments.
+
+```js
+api.transform({ test: /\.pug$/, environments: ['web'] }, ({ code }) => {
+  // ...
+});
+```
+
 - `resourceQuery`: matches module's query, the same as Rspack's [Rule.resourceQuery](https://rspack.dev/config/module#ruleresourcequery).
 
 ```js

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

@@ -206,6 +206,7 @@ descriptor 参数是一个对象，用于描述模块的匹配条件。
 type TransformDescriptor = {
   test?: RuleSetCondition;
   targets?: RsbuildTarget[];
+  environments?: string[];
   resourceQuery?: RuleSetCondition;
   raw?: boolean;
 };
@@ -229,6 +230,14 @@ api.transform({ test: /\.pug$/, targets: ['web'] }, ({ code }) => {
 });
 ```
 
+- `environments`：匹配 Rsbuild [environment](/guide/advanced/environments) name，仅对匹配的 environments 应用当前 transform 函数。
+
+```js
+api.transform({ test: /\.pug$/, environments: ['web'] }, ({ code }) => {
+  // ...
+});
+```
+
 - `resourceQuery`：匹配模块的 query，等价于 Rspack 的 [Rule.resourceQuery](https://rspack.dev/config/module#ruleresourcequery)。
 
 ```js