feat: support registering async plugin in config (#1657)

e2e/cases/async-plugin/index.test.ts

@@ -0,0 +1,42 @@
+import { expect } from '@playwright/test';
+import { build, gotoPage, rspackOnlyTest } from '@e2e/helper';
+import type { RsbuildPlugin } from '@rsbuild/core';
+
+const asyncPlugin = async (): Promise<RsbuildPlugin> => {
+  await new Promise((resolve) => {
+    setTimeout(resolve);
+  });
+
+  return {
+    name: 'async-plugin',
+    setup(api) {
+      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
+        return mergeRsbuildConfig(config, {
+          source: {
+            define: {
+              ENABLE_TEST: JSON.stringify(true),
+            },
+          },
+        });
+      });
+    },
+  };
+};
+
+rspackOnlyTest(
+  'should allow to register async plugin in plugins field',
+  async ({ page }) => {
+    const rsbuild = await build({
+      cwd: __dirname,
+      runServer: true,
+      plugins: [asyncPlugin()],
+    });
+
+    await gotoPage(page, rsbuild);
+
+    const testEl = page.locator('#test-el');
+    await expect(testEl).toHaveText('aaaaa');
+
+    await rsbuild.close();
+  },
+);

e2e/cases/async-plugin/src/index.js

@@ -0,0 +1,12 @@
+if (ENABLE_TEST === true) {
+  const test = document.createElement('div');
+  test.id = 'test-el';
+  test.innerHTML = 'aaaaa';
+  document.body.appendChild(test);
+}
+
+const testEl = document.createElement('div');
+testEl.id = 'test';
+testEl.innerHTML = 'Hello Rsbuild!';
+
+document.body.appendChild(testEl);

e2e/scripts/shared.ts

@@ -8,6 +8,7 @@ import { pluginSwc } from '@rsbuild/plugin-swc';
 import type {
   RsbuildConfig,
   RsbuildPlugin,
+  RsbuildPlugins,
   CreateRsbuildOptions,
 } from '@rsbuild/core';
 import type { Page } from 'playwright';
@@ -33,31 +34,28 @@ const noop = async () => {};
 
 export const createRsbuild = async (
   rsbuildOptions: CreateRsbuildOptions,
-  plugins: RsbuildPlugin[] = [],
+  plugins: RsbuildPlugins = [],
 ) => {
   const { createRsbuild } = await import('@rsbuild/core');
 
+  rsbuildOptions.rsbuildConfig ||= {};
+  rsbuildOptions.rsbuildConfig.plugins = [
+    ...(rsbuildOptions.rsbuildConfig.plugins || []),
+    ...(plugins || []),
+  ];
+
   if (process.env.PROVIDE_TYPE === 'rspack') {
     const rsbuild = await createRsbuild(rsbuildOptions);
 
-    if (plugins) {
-      rsbuild.addPlugins(plugins);
-    }
-
     return rsbuild;
   }
 
   const { webpackProvider } = await import('@rsbuild/webpack');
 
-  rsbuildOptions.rsbuildConfig ||= {};
   rsbuildOptions.rsbuildConfig.provider = webpackProvider;
 
   const rsbuild = await createRsbuild(rsbuildOptions);
 
-  if (plugins) {
-    rsbuild.addPlugins(plugins);
-  }
-
   const swc = pluginSwc();
   if (!rsbuild.isPluginExists(swc.name)) {
     rsbuild.addPlugins([swc]);
@@ -177,7 +175,7 @@ export async function build({
   runServer = false,
   ...options
 }: CreateRsbuildOptions & {
-  plugins?: RsbuildPlugin[];
+  plugins?: RsbuildPlugins;
   runServer?: boolean;
 }) {
   process.env.NODE_ENV = 'production';

packages/core/src/createRsbuild.ts

@@ -78,7 +78,8 @@ export async function createRsbuild(
   };
 
   if (rsbuildConfig.plugins) {
-    rsbuild.addPlugins(rsbuildConfig.plugins);
+    const plugins = await Promise.all(rsbuildConfig.plugins);
+    rsbuild.addPlugins(plugins);
   }
 
   return rsbuild;

packages/core/src/pluginManager.ts

@@ -1,8 +1,8 @@
 import { color, debug, logger, isFunction } from '@rsbuild/shared';
 import type {
+  Falsy,
   PluginManager,
   RsbuildPlugin,
-  RsbuildPlugins,
   RsbuildPluginAPI,
   BundlerPluginInstance,
 } from '@rsbuild/shared';
@@ -54,7 +54,7 @@ export function createPluginManager(): PluginManager {
   let plugins: RsbuildPlugin[] = [];
 
   const addPlugins = (
-    newPlugins: RsbuildPlugins,
+    newPlugins: Array<RsbuildPlugin | Falsy>,
     options?: { before?: string },
   ) => {
     const { before } = options || {};

packages/document/docs/en/config/plugins.mdx

@@ -1,10 +1,25 @@
 # plugins
 
-Used to register Rsbuild plugins. Please check the [Plugin List](/plugins/list/index) to discover available plugins.
+Used to register Rsbuild plugins.
+
+Async plugin (promise) in the plugins array will be resolved, and falsy values will be ignored.
+
+- **Type:**
+
+```ts
+type Falsy = false | null | undefined;
+
+type RsbuildPlugins = (
+  | RsbuildPlugin
+  | Falsy
+  | Promise<RsbuildPlugin | Falsy>
+)[];
+```
 
-- **Type:** `RsbuildPlugin[]`
 - **Default:** `undefined`
 
+> Please check out the [Plugin List](/plugins/list/index) page to discover all available plugins.
+
 ## Example
 
 For example, register the Stylus plugin in Rsbuild.

packages/document/docs/zh/config/plugins.mdx

@@ -1,10 +1,25 @@
 # plugins
 
-用于注册 Rsbuild 插件，请查看[插件列表](/plugins/list/index) 来发现可用的插件。
+用于注册 Rsbuild 插件。
+
+插件数组中的异步插件（promise）会自动被 resolve，falsy value 会被忽略。
+
+- **类型：**
+
+```ts
+type Falsy = false | null | undefined;
+
+type RsbuildPlugins = (
+  | RsbuildPlugin
+  | Falsy
+  | Promise<RsbuildPlugin | Falsy>
+)[];
+```
 
-- **类型：** `RsbuildPlugin[]`
 - **默认值：** `undefined`
 
+> 请查看[插件列表](/plugins/list/index)页面来发现所有可用的插件。
+
 ## 示例
 
 比如注册 Rsbuild 的 Stylus 插件。
@@ -64,6 +79,12 @@ export default defineConfig({
 });
 ```
 
+## 异步插件
+
+```ts
+import { RsbuildPlugin } from '@rsbuild/core';
+```
+
 ## Rspack 插件
 
 `plugins` 选项用于注册 Rsbuild 插件，如果你需要注册 Rspack 或 Webpack 插件，请使用 [tools.rspack](/config/tools/rspack)。

packages/shared/src/types/plugin.ts

@@ -73,7 +73,10 @@ export type ModifyWebpackConfigFn = (
 
 export type PluginManager = {
   readonly plugins: RsbuildPlugin[];
-  addPlugins: (plugins: RsbuildPlugins, options?: { before?: string }) => void;
+  addPlugins: (
+    plugins: Array<RsbuildPlugin | Falsy>,
+    options?: { before?: string },
+  ) => void;
   removePlugins: (pluginNames: string[]) => void;
   isPluginExists: (pluginName: string) => boolean;
   /** The plugin API. */
@@ -108,7 +111,11 @@ export type RsbuildPlugin = {
   remove?: string[];
 };
 
-export type RsbuildPlugins = (RsbuildPlugin | Falsy)[];
+export type RsbuildPlugins = (
+  | RsbuildPlugin
+  | Falsy
+  | Promise<RsbuildPlugin | Falsy>
+)[];
 
 type PluginsFn<T = undefined> = T extends undefined
   ? () => Promise<RsbuildPlugin>