配置

Storybook Rsbuild 提供了多种自定义构建流程和行为的方式。本指南介绍可在 .storybook/main.ts 中使用的配置项。

Storybook 文档

本指南聚焦于 Rsbuild 特有的配置。关于通用的 Storybook 配置（stories、addons、refs 等），请参阅 Storybook Configure 文档。

rsbuildFinal

rsbuildFinal 字段让你能够直接访问 Rsbuild 配置。你可以用它来自定义构建配置，类似于 Webpack builder 中的 webpackFinal。

该函数接收当前的 Rsbuild 配置和一个 options 对象，并应返回修改后的配置。

使用

mergeRsbuildConfig 进行修改在 rsbuildFinal 中应始终使用来自 @rsbuild/core 的 mergeRsbuildConfig 修改配置；不支持返回全新的配置对象。直接替换 config.tools.rspack = {...} 等属性也可能被静默忽略，因为内部配置可能是由函数和对象组成的数组。使用函数形式的 tools.rspack 时，请修改并返回传入的配置，或使用回调提供的 mergeConfig；返回全新对象会静默丢弃 Storybook 注入的配置，例如 sb.mock 机制。

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild'
import { import mergeRsbuildConfigmergeRsbuildConfig } from '@rsbuild/core'

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: string[]stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: never[]addons: [],
  async function rsbuildFinal(config: any, { configType }: {
    configType: any;
}): Promise<any>
rsbuildFinal(config: anyconfig, { configType: anyconfigType }) {
    // Customize Rsbuild config here
    if (configType: anyconfigType === 'PRODUCTION') {
      return import mergeRsbuildConfigmergeRsbuildConfig(config: anyconfig, {
        performance: {
    removeConsole: boolean;
}
performance: {
          removeConsole: booleanremoveConsole: true,
        },
      })
    }

    // Example: add resolve alias
    return import mergeRsbuildConfigmergeRsbuildConfig(config: anyconfig, {
      resolve: {
    alias: {
        '@components': string;
    };
}
resolve: {
        alias: {
    '@components': string;
}
alias: {
          '@components': './src/components',
        },
      },
    })
  },
}

export default const config: StorybookConfigconfig

Builder 选项

你可以通过 core.builder 选项配置底层的 Rsbuild builder。

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild'

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: never[]stories: [],
  core: {
    builder: {
        name: string;
        options: {
            rsbuildConfigPath: string;
            fsCache: boolean;
        };
    };
}
core: {
    builder: {
    name: string;
    options: {
        rsbuildConfigPath: string;
        fsCache: boolean;
    };
}
builder: {
      name: stringname: 'storybook-builder-rsbuild',
      options: {
    rsbuildConfigPath: string;
    fsCache: boolean;
}
options: {
        // Path to your existing rsbuild.config.ts
        // Defaults to the root rsbuild.config.ts if found
        rsbuildConfigPath: stringrsbuildConfigPath: './custom-rsbuild.config.ts',

        // Enable filesystem cache for faster rebuilds
        // Default: false
        fsCache: booleanfsCache: true,

        // Lazy-compile entries as well as dynamic imports
        // lazyCompilation: true,

        // Specify Rsbuild environment to use (for multi-environment configs)
        // environment: 'web',
      },
    },
  },
}

export default const config: StorybookConfigconfig

继承的 Rsbuild 配置

rsbuildConfigPath 选中的配置会自动合并到 Storybook preview 构建中。仅用于生产环境的设置可能影响或破坏 preview，因此不会继承以下字段：

source.entry
output.distPath、output.filename、output.cleanDistPath、output.externals 和 output.assetPrefix
server.publicDir
dev.progressBar、dev.assetPrefix 和 dev.writeToDisk
tools.htmlPlugin
tools.rspack.output.library、tools.rspack.output.globalObject 和 tools.rspack.output.umdNamedDefine

此边界也适用于从 storybook-addon-rslib 和 storybook-addon-modernjs 继承的配置。tools.rspack 如果使用函数形式，内部字段将无法被检查和剥离。建议通过 environment 选择专用于 Storybook 的 Rsbuild environment。如果确实需要恢复某个已剥离的字段，请在 Storybook 的 rsbuildFinal 中显式添加；显式配置会在继承配置被剥离后执行。

Plugin 会继续继承，因为它们通常提供 preview build 所需的 transform。Storybook CLI 会在加载项目配置前将 process.env.STORYBOOK 设置为 'true'，可以用这个条件排除不应在 Storybook 中运行、仅供应用使用的 plugin。

选项参考

Option	Type	Default	Description
`rsbuildConfigPath`	`string`	`cwd/rsbuild.config.ts`	待合并的已有 Rsbuild 配置文件路径。
`fsCache`	`boolean`	`false`	启用 Rspack 的持久化文件系统缓存。
`lazyCompilation`	`boolean` \| `LazyCompilationOptions`	`{ entries: false }`（development）；`false`（production）	配置 Rspack 的 lazy compilation。
`environment`	`string`	`undefined`	从 Rsbuild 配置中选择特定的 environment。

在 development 中，默认值 { entries: false } 会立即编译 entry chunk，同时对 dynamically imported story module 使用 lazy compilation。在 production 中，此 builder option 不会应用，因此 lazy compilation 默认保持关闭；底层 Rsbuild 或 Rspack 配置仍可覆盖该行为。在 development 中，自动检测到 MSW 也会将默认值改为 false，除非你显式配置此选项。这与 Storybook webpack builder 不同，后者的 lazy compilation 是 opt-in，除非显式启用，否则保持关闭。

Webpack Addons 兼容性

由于 Rspack 兼容 webpack 的 loader/plugin API，你通常可以使用为 Webpack 设计的 Storybook addon。为此，请使用 webpackAddons 字段而非 addons。

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild'

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: never[]stories: [],
  // Addons that depend on Webpack loaders/plugins
  webpackAddons: string[]webpackAddons: ['@storybook/addon-coverage'],
}

export default const config: StorybookConfigconfig

Framework 选项

framework 特有的选项让你能够为 React、Vue 等定制行为。

React 选项

对于 storybook-react-rsbuild，你可以配置 reactDocgen 和 legacy root API。

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild'

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: {
    name: string;
    options: {
        strictMode: boolean;
        legacyRootApi: boolean;
    };
}
framework: {
    name: stringname: 'storybook-react-rsbuild',
    options: {
    strictMode: boolean;
    legacyRootApi: boolean;
}
options: {
      // Configure strict mode
      strictMode: booleanstrictMode: true,

      // Use legacy ReactDOM.render instead of createRoot (React 18+)
      legacyRootApi: booleanlegacyRootApi: false,
    },
  },
  stories: never[]stories: [],
  typescript: {
    reactDocgen: string;
    reactDocgenTypescriptOptions: {
        propFilter: (prop: any) => boolean;
    };
}
typescript: {
    // Configure docgen for TypeScript
    // 'react-docgen-typescript' | 'react-docgen' | false
    reactDocgen: stringreactDocgen: 'react-docgen-typescript',

    // Pass options to react-docgen-typescript-plugin
    reactDocgenTypescriptOptions: {
    propFilter: (prop: any) => boolean;
}
reactDocgenTypescriptOptions: {
      propFilter: (prop: any) => booleanpropFilter: (prop: anyprop) => {
        return prop: anyprop.parent ? !/node_modules/.RegExp.test(string: string): booleanReturns a Boolean value that indicates whether or not a pattern exists in a searched string.
@paramstring  String on which to perform the search.test(prop: anyprop.parent.fileName) : true
      },
    },
  },
}

export default const config: StorybookConfigconfig

TypeScript 选项

Storybook Rsbuild 使用 @rsbuild/plugin-type-check 进行类型检查。你可以通过 typescript 字段对其进行配置。

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild'

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: never[]stories: [],
  typescript: {
    check: boolean;
    checkOptions: {
        typescript: {
            memoryLimit: number;
        };
    };
}
typescript: {
    // Enable/disable fork-ts-checker-webpack-plugin
    check: booleancheck: true,

    // Options passed to fork-ts-checker-webpack-plugin
    checkOptions: {
    typescript: {
        memoryLimit: number;
    };
}
checkOptions: {
      typescript: {
    memoryLimit: number;
}
typescript: {
        memoryLimit: numbermemoryLimit: 4096,
      },
    },
  },
}

export default const config: StorybookConfigconfig

通用的 TypeScript 配置请参阅 Storybook TypeScript 文档。

Preview 产物目录结构

storybook build 输出的 preview 产物采用扁平结构 —— 打包后的 JS 与 CSS 直接产出到输出目录（默认为 storybook-static），与官方 webpack5 builder 一致：

storybook-static/
├── iframe.html
├── main.<hash>.iframe.bundle.js
├── <chunk-id>.<hash>.iframe.bundle.js
├── <entry>.<hash>.css
├── <name>.<hash>.svg      # 被引入的 SVG 与 WebAssembly 同样位于根目录
└── static/media/          # 被引入的图片、字体与媒体资源

v3.4.0 之前的版本会将这些文件嵌套在 static/js/、static/js/async/ 和 static/css/ 下。

#配置

#rsbuildFinal

#Builder 选项

#继承的 Rsbuild 配置

#选项参考

#Webpack Addons 兼容性

#Framework 选项

#React 选项

#TypeScript 选项

#Preview 产物目录结构

配置

rsbuildFinal

Builder 选项

继承的 Rsbuild 配置

选项参考

Webpack Addons 兼容性

Framework 选项

React 选项

TypeScript 选项

Preview 产物目录结构