docs: recommend use mergeRsbuildConfig within rsbuildFinal

Author: fi3ework

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json",
   "assist": {
     "includes": ["**", "!**/*.vue"],
     "actions": { "source": { "organizeImports": "on" } }

pnpm-lock.yaml

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { mergeRsbuildConfig } from '@rsbuild/core'
 import { pluginBabel } from '@rsbuild/plugin-babel'
 import type { StorybookConfig } from 'storybook-react-native-web-rsbuild'
 
@@ -40,24 +41,24 @@ const config: StorybookConfig = {
     // This is needed because react-native-reanimated (in modulesToTranspile)
     // gets its JSX transformed to use nativewind/jsx-runtime, but can't resolve
     // nativewind from deep within pnpm's .pnpm directory structure
-    config.resolve ??= {}
-    config.resolve.alias = {
-      ...config.resolve.alias,
-      nativewind: nativewindPath,
-    }
-
-    config.plugins?.push(
-      pluginBabel({
-        // KEY: Only transform src files to avoid transforming Rsbuild internals
-        // Use [\\/] to match both Unix (/) and Windows (\) path separators
-        include: /[\\/]src[\\/]/,
-        babelLoaderOptions: {
-          presets: ['@babel/preset-typescript', 'nativewind/babel'],
-          plugins: ['@babel/plugin-proposal-export-namespace-from'],
+    return mergeRsbuildConfig(config, {
+      resolve: {
+        alias: {
+          nativewind: nativewindPath,
         },
-      }),
-    )
-    return config
+      },
+      plugins: [
+        pluginBabel({
+          // KEY: Only transform src files to avoid transforming Rsbuild internals
+          // Use [\\/] to match both Unix (/) and Windows (\) path separators
+          include: /[\\/]src[\\/]/,
+          babelLoaderOptions: {
+            presets: ['@babel/preset-typescript', 'nativewind/babel'],
+            plugins: ['@babel/plugin-proposal-export-namespace-from'],
+          },
+        }),
+      ],
+    })
   },
 }
 

sandboxes/react-native-web/.storybook/main.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { mergeRsbuildConfig } from '@rsbuild/core'
 import { pluginVue } from '@rsbuild/plugin-vue'
 import type { StorybookConfig } from 'storybook-vue3-rsbuild'
 
@@ -34,14 +35,18 @@ const config: StorybookConfig = {
   rsbuildFinal: (config) => {
     // Since HMR for Rspack is not supported by unplugin-vue as of now (https://github.com/unplugin/unplugin-vue/issues/162),
     // it's better to remove rsbuild-plugin-unplugin-vue and use @rsbuild/plugin-vue to handle all Vue files.
-    config.plugins = (config.plugins || []).filter((p) => {
+    const filteredPlugins = (config.plugins || []).filter((p) => {
       if (p && 'name' in p) {
         return p.name !== 'plugin-unplugin-vue'
       }
       return true
     })
-    config.plugins.push(pluginVue())
-    return config
+    return mergeRsbuildConfig(
+      { ...config, plugins: filteredPlugins },
+      {
+        plugins: [pluginVue()],
+      },
+    )
   },
 }
 

sandboxes/rslib-vue3-component/.storybook/main.ts

@@ -12,9 +12,14 @@ The `rsbuildFinal` field gives you direct access to the Rsbuild configuration. Y
 
 This function receives the current Rsbuild config and an options object, and should return the modified config.
 
+:::warning Use `mergeRsbuildConfig` for modifications
+Always use [`mergeRsbuildConfig`](https://rsbuild.rs/api/javascript-api/core#mergersbuildconfig) from `@rsbuild/core` to modify the config. Directly mutating properties like `config.tools.rspack = {...}` may not work because internal configs can be arrays of functions/objects, and direct assignment may be silently ignored.
+:::
+
 ```ts twoslash title=".storybook/main.ts"
 // @noErrors
 import type { StorybookConfig } from 'storybook-react-rsbuild';
+import { mergeRsbuildConfig } from '@rsbuild/core';
 
 const config: StorybookConfig = {
   framework: 'storybook-react-rsbuild',
@@ -23,16 +28,21 @@ const config: StorybookConfig = {
   async rsbuildFinal(config, { configType }) {
     // Customize Rsbuild config here
     if (configType === 'PRODUCTION') {
-      config.performance = {
-        ...config.performance,
-        removeConsole: true,
-      };
+      return mergeRsbuildConfig(config, {
+        performance: {
+          removeConsole: true,
+        },
+      });
     }
 
-    // You can modify config.source, config.tools, etc.
-    // config.source = { ...config.source, alias: { ... } };
-
-    return config;
+    // Example: add source alias
+    return mergeRsbuildConfig(config, {
+      source: {
+        alias: {
+          '@components': './src/components',
+        },
+      },
+    });
   },
 };
 

website/docs/guide/configuration.mdx

@@ -4,13 +4,17 @@
 
 The default Vite and webpack builders emit relative asset paths, but Rsbuild recommends absolute paths for deployment (see the [asset prefix tips](https://rsbuild.rs/config/output/asset-prefix#path-types:~:text=on%20file%20location.-,TIP,-It%27s%20not%20recommended)). To deploy Storybook at `https://example.com/sb-path`, set [`output.assetPrefix`](https://rsbuild.rs/config/output/asset-prefix).
 
-```diff
+```js
+import { mergeRsbuildConfig } from '@rsbuild/core'
+
 const config: StorybookConfig = {
   // --snip--
   rsbuildFinal: (config) => {
-+   config.output ??= {}
-+   config.output.assetPrefix = '/sb-path/'
-    return config
+    return mergeRsbuildConfig(config, {
+      output: {
+        assetPrefix: '/sb-path/',
+      },
+    })
   },
   // --snip--
 }

website/docs/guide/faq.mdx

@@ -339,27 +339,31 @@ pnpm add -D @babel/core babel-loader @babel/preset-flow @babel/preset-react
 2. Add a custom Rsbuild configuration in `.storybook/main.ts`:
 
 ```ts
+import { mergeRsbuildConfig } from '@rsbuild/core'
+
 const config: StorybookConfig = {
   framework: {
     name: 'storybook-react-native-web-rsbuild',
     options: {},
   },
   rsbuildFinal: async (config) => {
-    config.tools ??= {}
-    config.tools.bundlerChain = (chain) => {
-      // Add babel-loader for packages with Flow syntax
-      chain.module
-        .rule('flow')
-        .test(/\.jsx?$/)
-        .include.add(/node_modules\/(react-native|@react-native)/)
-        .end()
-        .use('babel')
-        .loader('babel-loader')
-        .options({
-          presets: ['@babel/preset-flow', '@babel/preset-react'],
-        })
-    }
-    return config
+    return mergeRsbuildConfig(config, {
+      tools: {
+        bundlerChain: (chain) => {
+          // Add babel-loader for packages with Flow syntax
+          chain.module
+            .rule('flow')
+            .test(/\.jsx?$/)
+            .include.add(/node_modules\/(react-native|@react-native)/)
+            .end()
+            .use('babel')
+            .loader('babel-loader')
+            .options({
+              presets: ['@babel/preset-flow', '@babel/preset-react'],
+            })
+        },
+      },
+    })
   },
 }
 ```

website/docs/guide/framework/react-native-web.mdx

@@ -30,12 +30,15 @@ Install the framework package to enable React support.
 
 ```js
 import { StorybookConfig } from 'storybook-react-rsbuild'
+import { mergeRsbuildConfig } from '@rsbuild/core'
 
 const config: StorybookConfig = {
   framework: 'storybook-react-rsbuild',
   rsbuildFinal: (config) => {
     // Customize the final Rsbuild config here
-    return config
+    return mergeRsbuildConfig(config, {
+      // your custom config
+    })
   },
 }
 

website/docs/guide/framework/react.mdx

@@ -29,12 +29,15 @@ Install the HTML framework package to enable vanilla stories.
 
 ```js
 import { StorybookConfig } from 'storybook-html-rsbuild'
+import { mergeRsbuildConfig } from '@rsbuild/core'
 
 const config: StorybookConfig = {
   framework: 'storybook-html-rsbuild',
   rsbuildFinal: (config) => {
     // Customize the final Rsbuild config here
-    return config
+    return mergeRsbuildConfig(config, {
+      // your custom config
+    })
   },
 }
 

website/docs/guide/framework/vanilla.mdx

@@ -30,12 +30,15 @@ Install the Vue framework package to enable Storybook support.
 
 ```js
 import { StorybookConfig } from 'storybook-vue3-rsbuild'
+import { mergeRsbuildConfig } from '@rsbuild/core'
 
 const config: StorybookConfig = {
   framework: 'storybook-vue3-rsbuild',
   rsbuildFinal: (config) => {
     // Customize the final Rsbuild config here
-    return config
+    return mergeRsbuildConfig(config, {
+      // your custom config
+    })
   },
 }