From 91e0e4cdf9c7f9e23ee40988803f9c9cb771c13d Mon Sep 17 00:00:00 2001 From: SoonIter Date: Fri, 11 Jul 2025 15:47:06 +0800 Subject: [PATCH 1/4] refactor!: replace builderPlugins with builderConfig.plugins --- packages/core/src/node/initRsbuild.ts | 22 +++---- .../core/src/node/route/RouteService.test.ts | 3 +- packages/core/src/node/route/RouteService.ts | 2 +- .../docs/en/api/config/config-build.mdx | 57 +++++++++---------- .../docs/en/guide/advanced/extend-build.mdx | 16 +++--- .../docs/zh/api/config/config-build.mdx | 57 +++++++++---------- .../docs/zh/guide/advanced/extend-build.mdx | 16 +++--- packages/plugin-preview/src/index.ts | 1 - packages/shared/src/types/index.ts | 6 +- 9 files changed, 86 insertions(+), 94 deletions(-) diff --git a/packages/core/src/node/initRsbuild.ts b/packages/core/src/node/initRsbuild.ts index 9be36b705..7522eba82 100644 --- a/packages/core/src/node/initRsbuild.ts +++ b/packages/core/src/node/initRsbuild.ts @@ -55,10 +55,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 +379,13 @@ async function createInternalBuildConfig( export async function initRsbuild( rootDir: string, - _config: UserConfig, + config: UserConfig, pluginDriver: PluginDriver, enableSSG: boolean, extraRsbuildConfig?: RsbuildConfig, ): Promise { 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 +394,19 @@ 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); const { createRsbuild, mergeRsbuildConfig } = await import('@rsbuild/core'); const internalRsbuildConfig = await createInternalBuildConfig( userDocRoot, - config, + mergedConfig, enableSSG, routeService, pluginDriver, @@ -421,12 +419,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/route/RouteService.test.ts b/packages/core/src/node/route/RouteService.test.ts index 639ded2b3..e029c80de 100644 --- 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 index c2f74ff3b..238c73e42 100644 --- 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 index e61e44449..76bf38b53 100644 --- 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'; - - - ### 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 index e37276dd0..0c36c2d29 100644 --- 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 index 4da72fdb7..ba9620291 100644 --- 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'; - - - ### 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 index b94682ab4..70ac832d4 100644 --- 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 index a443e29b8..3f558e74e 100644 --- a/packages/plugin-preview/src/index.ts +++ b/packages/plugin-preview/src/index.ts @@ -141,7 +141,6 @@ export function pluginPreview(options?: Options): RspressPlugin { // not copy files again copy: undefined, }, - plugins: config?.builderPlugins, }, builderConfig, ); diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts index 4b5c43663..e03bb56b9 100644 --- a/packages/shared/src/types/index.ts +++ b/packages/shared/src/types/index.ts @@ -1,4 +1,4 @@ -import type { RsbuildConfig, RsbuildPlugin } from '@rsbuild/core'; +import type { RsbuildConfig } from '@rsbuild/core'; import type { loadConfig } from '@rsbuild/core'; import type { RehypeShikiOptions } from '@shikijs/rehype'; import type { ZoomOptions } from 'medium-zoom'; @@ -165,10 +165,6 @@ export interface UserConfig { selector?: string; options?: ZoomOptions; }; - /** - * Add some extra builder plugins - */ - builderPlugins?: RsbuildPlugin[]; /** * Multi version config */ From 6d559280c6d38c01f8b4577c631dba4b4d987b33 Mon Sep 17 00:00:00 2001 From: SoonIter Date: Fri, 11 Jul 2025 16:04:03 +0800 Subject: [PATCH 2/4] chore: add hint --- packages/core/src/node/initRsbuild.ts | 6 +++++- packages/core/src/node/logger/hint.ts | 24 ++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/packages/core/src/node/initRsbuild.ts b/packages/core/src/node/initRsbuild.ts index 7522eba82..3c886830e 100644 --- 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, @@ -401,6 +404,7 @@ export async function initRsbuild( }); const mergedConfig = await modifyConfigWithAutoNavSide(config); + hintBuilderPluginsBreakingChange(mergedConfig); const { createRsbuild, mergeRsbuildConfig } = await import('@rsbuild/core'); diff --git a/packages/core/src/node/logger/hint.ts b/packages/core/src/node/logger/hint.ts index 114caca07..0ccabb58f 100644 --- 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,29 @@ export async function hintThemeBreakingChange(customThemeDir: string) { } } +export function hintBuilderPluginsBreakingChange(config: UserConfig) { + // @ts-ignore + if (config.builderPlugins && Array.isArray(config.builderPlugins)) { + 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. */ From 7561f8578b557e783d6f97533bc075c4d8ce836f Mon Sep 17 00:00:00 2001 From: SoonIter Date: Fri, 11 Jul 2025 17:18:58 +0800 Subject: [PATCH 3/4] chore: update --- packages/core/src/node/logger/hint.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/core/src/node/logger/hint.ts b/packages/core/src/node/logger/hint.ts index 0ccabb58f..3190289f1 100644 --- a/packages/core/src/node/logger/hint.ts +++ b/packages/core/src/node/logger/hint.ts @@ -46,8 +46,14 @@ export async function hintThemeBreakingChange(customThemeDir: string) { } export function hintBuilderPluginsBreakingChange(config: UserConfig) { - // @ts-ignore - if (config.builderPlugins && Array.isArray(config.builderPlugins)) { + if ( + // @ts-ignore config.builderPlugins is removed in V2 + config.builderPlugins && + // @ts-ignore + Array.isArray(config.builderPlugins) && + // @ts-ignore + 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`, ` From ca9281223e9126962efcab1daaf893ce7569645b Mon Sep 17 00:00:00 2001 From: SoonIter Date: Fri, 11 Jul 2025 17:34:40 +0800 Subject: [PATCH 4/4] chore: update --- packages/core/src/node/logger/hint.ts | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/packages/core/src/node/logger/hint.ts b/packages/core/src/node/logger/hint.ts index 3190289f1..fa5bb85ce 100644 --- a/packages/core/src/node/logger/hint.ts +++ b/packages/core/src/node/logger/hint.ts @@ -47,11 +47,9 @@ export async function hintThemeBreakingChange(customThemeDir: string) { export function hintBuilderPluginsBreakingChange(config: UserConfig) { if ( - // @ts-ignore config.builderPlugins is removed in V2 - config.builderPlugins && - // @ts-ignore + // config.builderPlugins is removed in V2 + 'builderPlugins' in config && Array.isArray(config.builderPlugins) && - // @ts-ignore config.builderPlugins.length > 0 ) { logger.error(