storybook-rsbuild（故事书 rsbuild）

Storybook Rsbuild

Step 1 — Detect scenario

Read package.json and project structure to determine existing Storybook state:

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

Fresh Setup Workflow

1. Detect ecosystem integration

Read package.json dependencies and devDependencies, check in order:

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

2. Detect UI framework

Infer the UI framework from app dependencies (react, vue, lit, etc.):

3. Set up Storybook

1. In monorepos, operate in the package that will host stories
2. Read and follow the framework guide matched above
3. Ensure .storybook/main.* uses the correct framework: '<storybook-*-rsbuild>'
4. Ensure package.json has storybook dev and storybook build scripts
5. Run Verification below

Migration Workflow

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

Follow these steps in order:

1. 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
2. Resolve version compatibility — read the "Version compatibility" section in the migration guide, select the correct storybook-rsbuild major based on installed Storybook version
3. 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
4. **Update .storybook/main.*** — apply the config changes exactly as shown in the migration guide for the detected framework
5. 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)
6. Handle addon compatibility — keep addons unchanged initially; if build errors indicate addon incompatibility, consult the migration guide's addon section and apply the recommended fix
7. Verify — confirm the migration is complete, then run Verification below

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.

Verification

1. storybook dev starts without errors
2. Stories render correctly
3. HMR works
4. storybook build completes
5. Check startup logs to confirm the Rsbuild builder is active (not 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

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

Configuration

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

Examples

For working sandboxes → https://storybook.rsbuild.rs/guide/examples