refactor!: remove builderPlugins and migrate it to builderConfig.plugins (#2371)

SoonIter · web-flow · commit fc125cbc6e59 · 2025-07-14T06:54:38.000Z
diff --git a/packages/core/src/node/initRsbuild.ts b/packages/core/src/node/initRsbuild.ts
@@ -30,7 +30,10 @@ import {
   inlineThemeScript,
   isProduction,
 } from './constants';
-import { hintThemeBreakingChange } from './logger/hint';
+import {
+  hintBuilderPluginsBreakingChange,
+  hintThemeBreakingChange,
+} from './logger/hint';
 import { RouteService } from './route/RouteService';
 import {
   getVirtualModulesFromPlugins,
@@ -55,10 +58,9 @@ import { getSocialIcons } from './utils/getSocialIcons';
 
 function isPluginIncluded(config: UserConfig, pluginName: string): boolean {
   return Boolean(
-    config.builderPlugins?.some(plugin => plugin.name === pluginName) ||
-      config.builderConfig?.plugins?.some(
-        plugin => plugin && (plugin as RsbuildPlugin).name === pluginName,
-      ),
+    config.builderConfig?.plugins?.some(
+      plugin => plugin && (plugin as RsbuildPlugin).name === pluginName,
+    ),
   );
 }
 
@@ -380,14 +382,13 @@ async function createInternalBuildConfig(
 
 export async function initRsbuild(
   rootDir: string,
-  _config: UserConfig,
+  config: UserConfig,
   pluginDriver: PluginDriver,
   enableSSG: boolean,
   extraRsbuildConfig?: RsbuildConfig,
 ): Promise<RsbuildInstance> {
   const cwd = process.cwd();
-  const userDocRoot = path.resolve(rootDir || _config?.root || cwd);
-  const builderPlugins = _config?.builderPlugins ?? [];
+  const userDocRoot = path.resolve(rootDir || config?.root || cwd);
   // We use a temp dir to store runtime files, so we can separate client and server build
   // and we should empty temp dir before build
   // TODO: remove all the temp dir
@@ -396,19 +397,20 @@ export async function initRsbuild(
   await fs.mkdir(runtimeAbsTempDir, { recursive: true });
 
   const routeService = await RouteService.create({
-    config: _config,
+    config: config,
     runtimeTempDir: runtimeAbsTempDir,
     scanDir: userDocRoot,
     pluginDriver,
   });
 
-  const config = await modifyConfigWithAutoNavSide(_config);
+  const mergedConfig = await modifyConfigWithAutoNavSide(config);
+  hintBuilderPluginsBreakingChange(mergedConfig);
 
   const { createRsbuild, mergeRsbuildConfig } = await import('@rsbuild/core');
 
   const internalRsbuildConfig = await createInternalBuildConfig(
     userDocRoot,
-    config,
+    mergedConfig,
     enableSSG,
     routeService,
     pluginDriver,
@@ -421,12 +423,10 @@ export async function initRsbuild(
       ...(pluginDriver
         .getPlugins()
         ?.map(plugin => plugin.builderConfig ?? {}) || []),
-      config?.builderConfig || {},
+      mergedConfig.builderConfig || {},
       extraRsbuildConfig || {},
     ),
   });
 
-  rsbuild.addPlugins(builderPlugins);
-
   return rsbuild;
 }
diff --git a/packages/core/src/node/logger/hint.ts b/packages/core/src/node/logger/hint.ts
@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
+import type { UserConfig } from '@rspress/shared';
 import { logger } from '@rspress/shared/logger';
 import picocolors from 'picocolors';
 import type { NavJson } from '../auto-nav-sidebar/type';
@@ -44,6 +45,33 @@ export async function hintThemeBreakingChange(customThemeDir: string) {
   }
 }
 
+export function hintBuilderPluginsBreakingChange(config: UserConfig) {
+  if (
+    // config.builderPlugins is removed in V2
+    'builderPlugins' in config &&
+    Array.isArray(config.builderPlugins) &&
+    config.builderPlugins.length > 0
+  ) {
+    logger.error(
+      `[Rspress v2] The "builderPlugins" option has been renamed to "builderConfig.plugins", please update your config accordingly (https://rspress.rs/api/config/config-build#builderconfigplugins).\n`,
+      `
+export default defineConfig({
+${picocolors.redBright(
+  `  builderPlugins: [
+    pluginFoo()
+  ],`,
+)}
+${picocolors.greenBright(`  builderConfig: {
+    plugins: [
+      pluginFoo()
+    ],
+  },`)}
+});`,
+    );
+    process.exit(1);
+  }
+}
+
 /**
  * Possible reasons for printing "ssg: false" and some troubleshooting guidelines for users.
  */
diff --git a/packages/core/src/node/route/RouteService.test.ts b/packages/core/src/node/route/RouteService.test.ts
@@ -18,8 +18,7 @@ async function initRouteService(
   });
 
   const { routeData } = routeService;
-  const routeMeta = routeService.getRoutes();
-  const routeCode = routeService.generateRoutesCodeByRouteMeta(routeMeta);
+  const routeCode = routeService.generateRoutesCode();
 
   return {
     routeData,
diff --git a/packages/core/src/node/route/RouteService.ts b/packages/core/src/node/route/RouteService.ts
@@ -192,7 +192,7 @@ export class RouteService {
     return this.generateRoutesCodeByRouteMeta(this.getRoutes());
   }
 
-  generateRoutesCodeByRouteMeta(routeMeta: RouteMeta[]) {
+  private generateRoutesCodeByRouteMeta(routeMeta: RouteMeta[]) {
     return `
 import React from 'react';
 import { lazyWithPreload } from "react-lazy-with-preload";
diff --git a/packages/document/docs/en/api/config/config-build.mdx b/packages/document/docs/en/api/config/config-build.mdx
@@ -42,7 +42,7 @@ If you want to modify the output directory, please use [outDir](/api/config/conf
 
 :::
 
-## builderPlugins
+## builderConfig.plugins
 
 - Type: `RsbuildPlugin[]`
 
@@ -57,7 +57,9 @@ import { defineConfig } from 'rspress/config';
 import { pluginVue } from '@rsbuild/plugin-vue';
 
 export default defineConfig({
-  builderPlugins: [pluginVue()],
+  builderConfig: {
+    plugins: [pluginVue()],
+  },
 });
 ```
 
@@ -68,12 +70,14 @@ import { defineConfig } from 'rspress/config';
 import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginGoogleAnalytics({
-      // replace this with your Google tag ID
-      id: 'G-xxxxxxxxxx',
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginGoogleAnalytics({
+        // replace this with your Google tag ID
+        id: 'G-xxxxxxxxxx',
+      }),
+    ],
+  },
 });
 ```
 
@@ -84,13 +88,15 @@ import { defineConfig } from 'rspress/config';
 import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginOpenGraph({
-      title: 'My Website',
-      type: 'website',
-      // ...options
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginOpenGraph({
+        title: 'My Website',
+        type: 'website',
+        // ...options
+      }),
+    ],
+  },
 });
 ```
 
@@ -103,11 +109,13 @@ import { defineConfig } from 'rspress/config';
 import { pluginReact } from '@rsbuild/plugin-react';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginReact({
-      // ...options
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginReact({
+        // ...options
+      }),
+    ],
+  },
 });
 ```
 
@@ -195,15 +203,6 @@ export default defineConfig({
 
 After enabling this config, Rspress will check the links in the document based on the conventional routing table. If there is an unreachable link, the build will throw an error and exit.
 
-### markdown.mdxRs
-
-- Type: `boolean | { include: (filepath: string) => boolean }`
-- Default: `true`
-
-import MdxRs from '../../fragments/mdx-rs';
-
-<MdxRs />
-
 ### markdown.showLineNumbers
 
 - Type: `boolean`
diff --git a/packages/document/docs/en/guide/advanced/extend-build.mdx b/packages/document/docs/en/guide/advanced/extend-build.mdx
@@ -22,7 +22,7 @@ export default defineConfig({
 });
 ```
 
-Rspress also provides the [builderPlugins](/api/config/config-build#builderplugins) config to register Rsbuild plugins. You can leverage Rsbuild's extensive plugin ecosystem to enhance and extend your build capabilities.
+Rspress also provides the [builderConfig.plugins](/api/config/config-build#builderconfigplugins) config to register Rsbuild plugins. You can leverage Rsbuild's extensive plugin ecosystem to enhance and extend your build capabilities.
 
 For example, add Google analytics through [rsbuild-plugin-google-analytics](https://github.com/rspack-contrib/rsbuild-plugin-google-analytics):
 
@@ -31,12 +31,14 @@ import { defineConfig } from 'rspress/config';
 import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginGoogleAnalytics({
-      // replace this with your Google tag ID
-      id: 'G-xxxxxxxxxx',
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginGoogleAnalytics({
+        // replace this with your Google tag ID
+        id: 'G-xxxxxxxxxx',
+      }),
+    ],
+  },
 });
 ```
 
diff --git a/packages/document/docs/zh/api/config/config-build.mdx b/packages/document/docs/zh/api/config/config-build.mdx
@@ -42,7 +42,7 @@ export default defineConfig({
 
 :::
 
-## builderPlugins
+## builderConfig.plugins
 
 - Type: `RsbuildPlugin[]`
 
@@ -57,7 +57,9 @@ import { defineConfig } from 'rspress/config';
 import { pluginVue } from '@rsbuild/plugin-vue';
 
 export default defineConfig({
-  builderPlugins: [pluginVue()],
+  builderConfig: {
+    plugins: [pluginVue()],
+  },
 });
 ```
 
@@ -68,12 +70,14 @@ import { defineConfig } from 'rspress/config';
 import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginGoogleAnalytics({
-      // replace this with your Google tag ID
-      id: 'G-xxxxxxxxxx',
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginGoogleAnalytics({
+        // replace this with your Google tag ID
+        id: 'G-xxxxxxxxxx',
+      }),
+    ],
+  },
 });
 ```
 
@@ -84,13 +88,15 @@ import { defineConfig } from 'rspress/config';
 import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginOpenGraph({
-      title: 'My Website',
-      type: 'website',
-      // ...options
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginOpenGraph({
+        title: 'My Website',
+        type: 'website',
+        // ...options
+      }),
+    ],
+  },
 });
 ```
 
@@ -103,11 +109,13 @@ import { defineConfig } from 'rspress/config';
 import { pluginReact } from '@rsbuild/plugin-react';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginReact({
-      // ...options
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginReact({
+        // ...options
+      }),
+    ],
+  },
 });
 ```
 
@@ -195,15 +203,6 @@ export default defineConfig({
 
 开启这个配置后，Rspress 会基于约定式路由表对文档中的链接进行检查，若出现无法访问的链接，构建会抛出错误并退出。
 
-### markdown.mdxRs
-
-- Type: `boolean | { include: (filepath: string) => boolean }`
-- Default: `true`
-
-import MdxRs from '../../fragments/mdx-rs';
-
-<MdxRs />
-
 ### markdown.showLineNumbers
 
 - Type: `boolean`
diff --git a/packages/document/docs/zh/guide/advanced/extend-build.mdx b/packages/document/docs/zh/guide/advanced/extend-build.mdx
@@ -24,7 +24,7 @@ export default defineConfig({
 });
 ```
 
-Rspress 还提供了 [builderPlugins](/api/config/config-build#builderplugins) 配置项来注册 Rsbuild 插件。你可以利用 Rsbuild 丰富的插件生态来增强和扩展构建能力。
+Rspress 还提供了 [builderConfig.plugins](/api/config/config-build#builderconfigplugins) 配置项来注册 Rsbuild 插件。你可以利用 Rsbuild 丰富的插件生态来增强和扩展构建能力。
 
 比如通过 [rsbuild-plugin-google-analytics](https://github.com/rspack-contrib/rsbuild-plugin-google-analytics) 添加 Google analytics：
 
@@ -33,12 +33,14 @@ import { defineConfig } from 'rspress/config';
 import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';
 
 export default defineConfig({
-  builderPlugins: [
-    pluginGoogleAnalytics({
-      // replace this with your Google tag ID
-      id: 'G-xxxxxxxxxx',
-    }),
-  ],
+  builderConfig: {
+    plugins: [
+      pluginGoogleAnalytics({
+        // replace this with your Google tag ID
+        id: 'G-xxxxxxxxxx',
+      }),
+    ],
+  },
 });
 ```
 
diff --git a/packages/plugin-preview/src/index.ts b/packages/plugin-preview/src/index.ts
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts

Original file line number	Diff line number	Diff line change
`@@ -192,7 +192,7 @@ export class RouteService {`
`192`	`192`	`return this.generateRoutesCodeByRouteMeta(this.getRoutes());`
`193`	`193`	`}`
`194`	`194`
`195`		`- generateRoutesCodeByRouteMeta(routeMeta: RouteMeta[]) {`
	`195`	`+ private generateRoutesCodeByRouteMeta(routeMeta: RouteMeta[]) {`
`196`	`196`	return `
`197`	`197`	`import React from 'react';`
`198`	`198`	`import { lazyWithPreload } from "react-lazy-with-preload";`