storybook-rsbuild

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Storybook Rsbuild

Goal

目标

Set up Storybook on Rsbuild, or migrate an existing Storybook to it. Factual mappings — version compatibility, package names, install commands, config conversion patterns — live in upstream docs at

storybook.rsbuild.rs

. This skill is an action router and a behavioral checklist; it does not duplicate the docs.

在Rsbuild上设置Storybook，或是将现有Storybook迁移至Rsbuild。版本兼容性、包名、安装命令、配置转换模式等事实映射信息可在上游文档

storybook.rsbuild.rs

中查看。本指南是一个操作路由和行为检查清单，不会重复文档内容。

Principles (must follow)

原则（必须遵守）

Single source of truth is upstream. Fetch the relevant
```
storybook.rsbuild.rs
```
page for version tables, install commands, and config conversion patterns. Do not infer version pins or package names from training memory — the ecosystem moves faster than the model's prior.
Pin from the framework guide's Requirements table. Each framework guide page (e.g.
```
https://storybook.rsbuild.rs/guide/framework/react
```
) carries a Requirements section listing the canonical compatible version ranges — that is the authoritative source for version pins. For fresh setups, install the latest stable
```
storybook
```
major and the matching
```
storybook-rsbuild
```
major. Do not pin from version numbers you see in code snippets elsewhere; only the docs are authoritative.
Declare
@rsbuild/core
directly.
```
storybook-<framework>-rsbuild
```
lists
```
@rsbuild/core
```
as a peer dependency, but you must still add
```
@rsbuild/core
```
to the project's own
```
devDependencies
```
so version pins and lockfile audits remain unambiguous and a future framework-package release that drops the peer cannot silently break the build.
Migration is one task with two ordered phases — both required. Phase A: install the new framework package and update config; leave the old framework package, old builder package, and old
```
webpackFinal
```
/
```
viteFinal
```
blocks in place so Verification has a rollback path. Phase B: as soon as Verification passes, in the same task, remove the old framework package (e.g.
```
@storybook/react-webpack5
```
,
```
@storybook/vue3-vite
```
), the old builder package (e.g.
```
@storybook/builder-webpack5
```
,
```
@storybook/builder-vite
```
), and the old
```
webpackFinal
```
/
```
viteFinal
```
block. A migration that ends with both builders' framework packages still in
```
package.json
```
is incomplete — leaving them is the most common silent regression in this skill's evals. Phase A on its own is not a valid stopping point; if you ran Verification, you must also run cleanup.
Preserve addons; never silently drop. When migrating, webpack-only addons (e.g.
```
@storybook/addon-styling-webpack
```
) must either be passed through
```
webpackAddons
```
(so upstream auto-translation handles them) or replaced with the equivalent Rsbuild-native pipeline (
```
@rsbuild/plugin-postcss
```
,
```
tools.postcss
```
, etc.). A migration that removes a styling addon and produces a passing
```
storybook build
```
but a visually broken story tree is still a regression.
Operate in scope. In monorepos, modify only the package that hosts stories. Do not edit business source files unless the migration strictly requires it.

上游为唯一可信来源。获取
```
storybook.rsbuild.rs
```
的相关页面，以获取版本表、安装命令和配置转换模式。不要从训练记忆中推断版本固定值或包名——生态系统的更新速度快于模型的现有知识。
从框架指南的Requirements表中固定版本。每个框架指南页面（例如
```
https://storybook.rsbuild.rs/guide/framework/react
```
）都包含一个Requirements部分，列出了标准兼容版本范围——这是版本固定值的权威来源。对于全新搭建，安装最新稳定版的
```
storybook
```
主版本以及匹配的
```
storybook-rsbuild
```
主版本。不要从其他地方的代码片段中看到的版本号来固定版本；只有文档是权威的。
直接声明
@rsbuild/core
。
```
storybook-<framework>-rsbuild
```
将
```
@rsbuild/core
```
列为peer依赖，但你仍需将
```
@rsbuild/core
```
添加到项目自身的
```
devDependencies
```
中，这样版本固定值和锁文件审计才能保持明确，且未来框架包版本若移除该peer依赖也不会静默破坏构建。
迁移是一项包含两个有序阶段的任务——两个阶段均需完成。阶段A：安装新的框架包并更新配置；保留旧框架包、旧构建器包以及旧的
```
webpackFinal
```
/
```
viteFinal
```
代码块，以便验证阶段有回滚路径。阶段B：一旦验证通过，在同一任务中移除旧框架包（例如
```
@storybook/react-webpack5
```
、
```
@storybook/vue3-vite
```
）、旧构建器包（例如
```
@storybook/builder-webpack5
```
、
```
@storybook/builder-vite
```
）以及旧的
```
webpackFinal
```
/
```
viteFinal
```
代码块。若迁移结束后
```
package.json
```
中仍同时存在两个构建器的框架包，则视为未完成——遗留这些包是本指南评估中最常见的静默回归问题。仅完成阶段A并非有效终止点；若已执行验证，则必须执行清理步骤。
保留插件；切勿静默移除。迁移时，仅支持webpack的插件（例如
```
@storybook/addon-styling-webpack
```
）必须通过
```
webpackAddons
```
传递（以便上游自动转换处理），或是替换为Rsbuild原生的等效流水线（例如
```
@rsbuild/plugin-postcss
```
、
```
tools.postcss
```
等）。若迁移移除了样式插件，导致
```
storybook build
```
执行成功但故事树显示异常，仍视为回归问题。
在范围内操作。在单体仓库中，仅修改托管故事的包。除非迁移严格要求，否则不要编辑业务源文件。

Step 1 — Detect scenario

步骤1 — 检测场景

Read

package.json

and project structure to determine existing Storybook state:

Check for
```
.storybook/
```
directory (in monorepos, check both root and per-package)
Check
```
package.json
```
for
```
storybook
```
scripts or
```
@storybook/*
```
/
```
storybook-*-rsbuild
```
in dependencies or devDependencies
If Storybook exists and already uses
storybook-*-rsbuild
→ already set up; go to Configuration or Troubleshooting as needed
If Storybook exists with a non-Rsbuild builder (
```
@storybook/*-webpack5
```
,
```
@storybook/*-vite
```
, etc.) → go to Migration Workflow
No Storybook found → go to Fresh Setup Workflow

读取

package.json

和项目结构，确定现有Storybook状态：

检查是否存在
```
.storybook/
```
目录（在单体仓库中，同时检查根目录和各个子包目录）
检查
```
package.json
```
中的
```
storybook
```
脚本，或是依赖项/开发依赖项中的
```
@storybook/*
```
/
```
storybook-*-rsbuild
```
若Storybook已存在且已使用
storybook-*-rsbuild
→ 已完成设置；根据需要跳转至配置或故障排查
若Storybook已存在但使用非Rsbuild构建器（
```
@storybook/*-webpack5
```
、
```
@storybook/*-vite
```
等） → 跳转至迁移流程
未找到Storybook → 跳转至全新搭建流程

Fresh Setup Workflow

全新搭建流程

1. Detect ecosystem integration

1. 检测生态系统集成

Read

package.json

dependencies and devDependencies, check in order:

Signal	Ecosystem	Integration guide
`@rslib/core`	Rslib	https://storybook.rsbuild.rs/guide/integrations/rslib
`@modern-js/app-tools`	Modern.js	https://storybook.rsbuild.rs/guide/integrations/modernjs
`@rspack/core` without `@rsbuild/core`	Pure Rspack	https://storybook.rsbuild.rs/guide/integrations/rspack

If matched, read the integration guide and apply its constraints as an overlay alongside the steps below.

读取

package.json

的依赖项和开发依赖项，按以下顺序检查：

信号	生态系统	集成指南
`@rslib/core`	Rslib	https://storybook.rsbuild.rs/guide/integrations/rslib
`@modern-js/app-tools`	Modern.js	https://storybook.rsbuild.rs/guide/integrations/modernjs
`@rspack/core` 且无 `@rsbuild/core`	纯Rspack	https://storybook.rsbuild.rs/guide/integrations/rspack

若匹配成功，阅读集成指南并将其约束作为叠加层应用到以下步骤中。

2. Detect UI framework

2. 检测UI框架

Infer the UI framework from app dependencies (

react

vue

lit

, etc.):

UI Framework	Framework package	Guide
React	`storybook-react-rsbuild`	https://storybook.rsbuild.rs/guide/framework/react
Vue 3	`storybook-vue3-rsbuild`	https://storybook.rsbuild.rs/guide/framework/vue
Vanilla JS/TS	`storybook-html-rsbuild`	https://storybook.rsbuild.rs/guide/framework/vanilla
Web Components	`storybook-web-components-rsbuild`	https://storybook.rsbuild.rs/guide/framework/web-components
React Native Web	`storybook-react-native-web-rsbuild`	https://storybook.rsbuild.rs/guide/framework/react-native-web

从应用依赖项（

react

、

vue

、

lit

等）推断UI框架：

UI框架	框架包名称	指南
React	`storybook-react-rsbuild`	https://storybook.rsbuild.rs/guide/framework/react
Vue 3	`storybook-vue3-rsbuild`	https://storybook.rsbuild.rs/guide/framework/vue
Vanilla JS/TS	`storybook-html-rsbuild`	https://storybook.rsbuild.rs/guide/framework/vanilla
Web Components	`storybook-web-components-rsbuild`	https://storybook.rsbuild.rs/guide/framework/web-components
React Native Web	`storybook-react-native-web-rsbuild`	https://storybook.rsbuild.rs/guide/framework/react-native-web

3. Set up Storybook

3. 搭建Storybook

In monorepos, operate in the package that will host stories
Read and follow the framework guide matched above; install the latest stable
```
storybook
```
major and the matching
```
storybook-<framework>-rsbuild
```
major (Principle 2)

Add

@rsbuild/core

devDependencies

directly, alongside

storybook-<framework>-rsbuild

(Principle 3)

Ensure

.storybook/main.*

uses the correct

framework: '<storybook-*-rsbuild>'

Ensure

package.json

has

storybook dev

and

storybook build

scripts

If no story file exists yet, scaffold at least one minimal example story (e.g.
```
src/stories/Example.stories.*
```
) so Verification step 2 has something to render
Run Verification below

在单体仓库中，在托管故事的包目录下操作
阅读并遵循上述匹配的框架指南；安装最新稳定版的
```
storybook
```
主版本以及匹配的
```
storybook-<framework>-rsbuild
```
主版本（原则2）

将

@rsbuild/core

直接添加到

devDependencies

中，与

storybook-<framework>-rsbuild

并列（原则3）

确保

.storybook/main.*

使用正确的

framework: '<storybook-*-rsbuild>'

配置

确保

package.json

包含

storybook dev

和

storybook build

脚本

若尚未存在故事文件，至少生成一个最小示例故事（例如
```
src/stories/Example.stories.*
```
），以便验证步骤2有内容可渲染
执行下方的验证

Migration Workflow

迁移流程

Read the upstream migration guide: https://storybook.rsbuild.rs/guide/migration

Follow these steps in order:

Detect migration type — read
```
.storybook/main.*
```
(
```
framework
```
field and/or
```
core.builder
```
) and
```
package.json
```
dependencies to classify as "from webpack5" or "from Vite", then select the matching section in the migration guide
Resolve version compatibility — read the "Version compatibility" section in the migration guide, select the correct
```
storybook-rsbuild
```
major based on installed Storybook version
Replace packages — apply the install/remove mapping from the migration guide using the project's package manager (detect from lockfile); only change packages required by the migration. Always add
```
@rsbuild/core
```
as a direct devDep alongside the new framework package (Principle 3). Do not remove the old framework package or old devDeps yet — that happens after Verification (Principle 4)
Update
.storybook/main.*
— apply the config changes exactly as shown in the migration guide for the detected framework
Migrate custom builder hooks — search for legacy builder hooks (
```
webpackFinal
```
/
```
viteFinal
```
); if found, convert following the upstream configuration guide (https://storybook.rsbuild.rs/guide/configuration)
Handle addon compatibility — keep addons unchanged initially. If a webpack-only addon must change, route it through
```
webpackAddons
```
for upstream auto-translation, or replace it with the Rsbuild-native equivalent — never silently drop it (Principle 5). Consult the migration guide's addon section for the recommended fix
Verify, then clean up — both required — run Verification below; once it passes, in the same task complete all of the following before reporting done (Principle 4):
- Remove the old framework package from
```
package.json
```
  devDependencies (e.g.
```
@storybook/react-webpack5
```
  ,
```
@storybook/vue3-webpack5
```
  ,
```
@storybook/react-vite
```
  ,
```
@storybook/vue3-vite
```
  ,
```
@storybook/html-webpack5
```
  ,
```
@storybook/web-components-webpack5
```
  , etc.)
- Remove the old builder package if separately listed (e.g.
```
@storybook/builder-webpack5
```
  ,
```
@storybook/builder-vite
```
  )
- Delete the legacy
```
webpackFinal
```
  /
```
viteFinal
```
  block from
```
.storybook/main.*
```
- Drop any old-builder-only devDeps that no longer have consumers
- Re-run
```
pnpm install
```
  (or the project's package manager equivalent) so the lockfile reflects the cleanup

If a factual mapping is needed (version table, package names, conversion patterns) and not present in this skill, fetch it from the upstream docs — do not guess.

阅读上游迁移指南：https://storybook.rsbuild.rs/guide/migration

按以下顺序执行步骤：

检测迁移类型 — 读取
```
.storybook/main.*
```
（
```
framework
```
字段和/或
```
core.builder
```
）和
```
package.json
```
依赖项，分类为“从webpack5迁移”或“从Vite迁移”，然后选择迁移指南中对应的章节
解决版本兼容性 — 阅读迁移指南中的“Version compatibility”章节，根据已安装的Storybook版本选择正确的
```
storybook-rsbuild
```
主版本
替换包 — 使用项目的包管理器（从锁文件检测）应用迁移指南中的安装/移除映射；仅更改迁移所需的包。始终将
```
@rsbuild/core
```
作为直接开发依赖项添加到新框架包旁（原则3）。暂时不要移除旧框架包或旧开发依赖项——这将在验证完成后进行（原则4）
更新
.storybook/main.*
— 完全按照迁移指南中对应框架的说明应用配置更改
迁移自定义构建器钩子 — 搜索遗留构建器钩子（
```
webpackFinal
```
/
```
viteFinal
```
）；若存在，按照上游配置指南（https://storybook.rsbuild.rs/guide/configuration）进行转换
处理插件兼容性 — 初始阶段保持插件不变。若仅支持webpack的插件必须更改，通过
```
webpackAddons
```
传递以进行上游自动转换，或是替换为Rsbuild原生的等效插件——切勿静默移除（原则5）。查阅迁移指南的插件章节获取推荐修复方案
验证，然后清理——两者均需完成 — 执行下方的验证；一旦通过，在同一任务中完成以下所有操作后再报告完成（原则4）：
- 从
```
package.json
```
  的开发依赖项中移除旧框架包（例如
```
@storybook/react-webpack5
```
  、
```
@storybook/vue3-webpack5
```
  、
```
@storybook/react-vite
```
  、
```
@storybook/vue3-vite
```
  、
```
@storybook/html-webpack5
```
  、
```
@storybook/web-components-webpack5
```
  等）
- 若单独列出了旧构建器包，将其移除（例如
```
@storybook/builder-webpack5
```
  、
```
@storybook/builder-vite
```
  ）
- 从
```
.storybook/main.*
```
  中删除遗留的
```
webpackFinal
```
  /
```
viteFinal
```
  代码块
- 移除所有不再被引用的仅支持旧构建器的开发依赖项
- 重新运行
```
pnpm install
```
  （或项目包管理器的等效命令），使锁文件反映清理后的状态

若需要事实映射信息（版本表、包名、转换模式）且本指南未提供，请从上游文档获取——切勿猜测。

Verification

验证

```
storybook dev
```
starts without errors
At least one story renders correctly in the browser (a clean dev-server boot is not sufficient — a missing-glob in
```
stories
```
or a broken framework wiring will only surface here)
HMR works
```
storybook build
```
completes
Check startup logs to confirm the Rsbuild builder is active (not webpack/vite)

```
storybook dev
```
启动无错误
至少一个故事在浏览器中正确渲染（仅开发服务器成功启动并不足够——
```
stories
```
中的glob缺失或框架连接异常只会在此处显现）
HMR（热模块替换）正常工作
```
storybook build
```
执行完成
检查启动日志，确认Rsbuild构建器处于激活状态（而非webpack/vite）

Troubleshooting

故障排查

Cache issues: remove
```
node_modules/.cache/storybook
```
and retry
Residual config: if dev fails after migration, temporarily remove custom
```
rsbuildFinal
```
block to isolate the issue, then re-add incrementally
For debugging and other issues, consult the upstream migration guide's "Debugging" section and https://storybook.rsbuild.rs/guide/configuration

缓存问题：删除
```
node_modules/.cache/storybook
```
后重试
残留配置：若迁移后开发服务器启动失败，临时移除自定义的
```
rsbuildFinal
```
代码块以隔离问题，然后逐步重新添加
如需调试或解决其他问题，请查阅上游迁移指南的“Debugging”章节以及https://storybook.rsbuild.rs/guide/configuration

Edge Cases

边缘情况

Monorepo: locate the package that hosts stories; operate there, not at root
Multiple
.storybook/
dirs: pick the one referenced by
```
package.json
```
scripts
TS path aliases: ensure aliases are preserved after migration; consult the upstream configuration guide for how to configure
```
rsbuildFinal
```

单体仓库：定位托管故事的包；在该包目录下操作，而非根目录
多个
.storybook/
目录：选择
```
package.json
```
脚本中引用的目录
TS路径别名：确保迁移后别名仍保留；查阅上游配置指南了解如何配置
```
rsbuildFinal
```

Configuration

配置

For

rsbuildFinal

, builder options, TypeScript, and framework-specific options → read https://storybook.rsbuild.rs/guide/configuration

关于

rsbuildFinal

、构建器选项、TypeScript和框架特定选项 → 阅读https://storybook.rsbuild.rs/guide/configuration