feat: support nested plugins (#3348)

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

packages/core/src/createRsbuild.ts

@@ -1,3 +1,4 @@
+import { isPromise } from 'node:util/types';
 import { createContext } from './createContext';
 import { getNodeEnv, pick, setNodeEnv } from './helpers';
 import { initPluginAPI } from './initPlugins';
@@ -9,11 +10,14 @@ import type {
   Build,
   CreateDevServer,
   CreateRsbuildOptions,
+  Falsy,
   InternalContext,
   PluginManager,
   PreviewServerOptions,
   ResolvedCreateRsbuildOptions,
   RsbuildInstance,
+  RsbuildPlugin,
+  RsbuildPlugins,
   RsbuildProvider,
   StartDevServer,
 } from './types';
@@ -199,8 +203,19 @@ export async function createRsbuild(
     ]),
   };
 
+  const getFlattenedPlugins = async (pluginOptions: RsbuildPlugins) => {
+    let plugins = pluginOptions;
+    do {
+      plugins = (await Promise.all(plugins)).flat(
+        Number.POSITIVE_INFINITY as 1,
+      );
+    } while (plugins.some((v) => isPromise(v)));
+
+    return plugins as Array<RsbuildPlugin | Falsy>;
+  };
+
   if (rsbuildConfig.plugins) {
-    const plugins = await Promise.all(rsbuildConfig.plugins);
+    const plugins = await getFlattenedPlugins(rsbuildConfig.plugins);
     rsbuild.addPlugins(plugins);
   }
 
@@ -212,7 +227,7 @@ export async function createRsbuild(
           !rsbuildOptions.environment ||
           rsbuildOptions.environment.includes(name);
         if (config.plugins && isEnvironmentEnabled) {
-          const plugins = await Promise.all(config.plugins);
+          const plugins = await getFlattenedPlugins(config.plugins);
           rsbuild.addPlugins(plugins, {
             environment: name,
           });

packages/core/src/types/plugin.ts

@@ -201,7 +201,8 @@ type LooseRsbuildPlugin = Omit<RsbuildPlugin, 'setup'> & {
 export type RsbuildPlugins = (
   | LooseRsbuildPlugin
   | Falsy
-  | Promise<LooseRsbuildPlugin | Falsy>
+  | Promise<LooseRsbuildPlugin | Falsy | RsbuildPlugins>
+  | RsbuildPlugins
 )[];
 
 export type GetRsbuildConfig = {

packages/core/tests/builder.test.ts

@@ -23,3 +23,44 @@ describe('should use rspack as default bundler', () => {
     process.env.NODE_ENV = NODE_ENV;
   });
 });
+
+describe('plugins', () => {
+  it('should apply nested plugins correctly', async () => {
+    function myPlugin() {
+      return [
+        {
+          name: 'plugin-foo',
+          setup() {},
+        },
+        {
+          name: 'plugin-bar',
+          setup() {},
+        },
+      ];
+    }
+
+    const rsbuild = await createRsbuild({
+      rsbuildConfig: {
+        source: {
+          entry: {
+            index: './src/index.js',
+          },
+        },
+        plugins: [
+          myPlugin(),
+          Promise.resolve([
+            {
+              name: 'plugin-zoo',
+              setup() {},
+            },
+          ]),
+        ],
+      },
+    });
+
+    expect(rsbuild.isPluginExists('plugin-foo')).toBeTruthy();
+    expect(rsbuild.isPluginExists('plugin-bar')).toBeTruthy();
+    expect(rsbuild.isPluginExists('plugin-zoo')).toBeTruthy();
+    expect(rsbuild.isPluginExists('plugin-404')).toBeFalsy();
+  });
+});

scripts/test-helper/src/rsbuild.ts

@@ -1,7 +1,9 @@
+import { isPromise } from 'node:util/types';
 import type {
   BundlerPluginInstance,
   CreateRsbuildOptions,
   RsbuildInstance,
+  RsbuildPlugin,
   RsbuildPlugins,
   Rspack,
 } from '@rsbuild/core';
@@ -53,10 +55,21 @@ export async function createStubRsbuild({
 
   const rsbuild = await createRsbuild(rsbuildOptions);
 
+  const getFlattenedPlugins = async (pluginOptions: RsbuildPlugins) => {
+    let plugins = pluginOptions;
+    do {
+      plugins = (await Promise.all(plugins)).flat(
+        Number.POSITIVE_INFINITY as 1,
+      );
+    } while (plugins.some((v) => isPromise(v)));
+
+    return plugins as Array<RsbuildPlugin | false | null | undefined>;
+  };
+
   if (plugins) {
     // remove all builtin plugins
     rsbuild.removePlugins(rsbuild.getPlugins().map((item) => item.name));
-    rsbuild.addPlugins(await Promise.all(plugins));
+    rsbuild.addPlugins(await getFlattenedPlugins(plugins));
   }
 
   const unwrapConfig = async (index = 0) => {

website/docs/en/config/plugins.mdx

@@ -12,7 +12,8 @@ type Falsy = false | null | undefined;
 type RsbuildPlugins = (
   | RsbuildPlugin
   | Falsy
-  | Promise<RsbuildPlugin | Falsy>
+  | Promise<RsbuildPlugin | Falsy | RsbuildPlugins>
+  | RsbuildPlugins
 )[];
 ```
 
@@ -47,6 +48,23 @@ By default, plugins are executed in the order they appear in the `plugins` array
 
 When a plugin internally uses fields that control the order, such as `pre` and `post`, the execution order is adjusted based on them. See [Pre Plugins](/plugins/dev/core#pre-pluginss) for more details.
 
+## Nested Plugins
+
+Rsbuild also supports adding nested plugins. You can pass in an array containing multiple plugins, similar to a plugin preset collection. This is particularly useful for implementing complex functionalities that require a combination of multiple plugins (such as framework integration).
+
+```ts title="rsbuild.config.ts"
+function myPlugin() {
+  return [
+    fooPlugin(),
+    barPlugin()
+  ];
+}
+
+export default {
+  plugins: [myPlugin()]
+}
+```
+
 ## Local Plugins
 
 If your local code repository contains Rsbuild plugins, you can import them using relative paths.

website/docs/zh/config/plugins.mdx

@@ -12,7 +12,8 @@ type Falsy = false | null | undefined;
 type RsbuildPlugins = (
   | RsbuildPlugin
   | Falsy
-  | Promise<RsbuildPlugin | Falsy>
+  | Promise<RsbuildPlugin | Falsy | RsbuildPlugins>
+  | RsbuildPlugins
 )[];
 ```
 
@@ -47,6 +48,23 @@ export default defineConfig({
 
 当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，执行顺序会基于它们进行调整，详见 [前置插件](/plugins/dev/core#前置插件)。
 
+## 嵌套插件
+
+Rsbuild 还支持添加嵌套插件，你可以传入一个包含多个插件的数组，类似于一个插件预设集合，这对于实现需要多个插件组合的复杂功能（例如框架集成）很有帮助。
+
+```ts title="rsbuild.config.ts"
+function myPlugin() {
+  return [
+    fooPlugin(),
+    barPlugin()
+  ];
+}
+
+export default {
+  plugins: [myPlugin()]
+}
+```
+
 ## 本地插件
 
 如果本地代码仓库中包含了一些 Rsbuild 插件，你可以直接通过相对路径引入。