storybook-rsbuild

What this skill does

# 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.

## Principles (must follow)

1. **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.

2. **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.

3. **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.

4. **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](#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.

5. **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.

6. **Operate in scope.** In monorepos, modify only the package that hosts stories. Do not edit business source files unless the migration strictly requires it.

## 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](#configuration) or [Troubleshooting](#troubleshooting) as needed
4. If Storybook exists **with a non-Rsbuild builder** (`@storybook/*-webpack5`, `@storybook/*-vite`, etc.) → go to [Migration Workflow](#migration-workflow)
5. **No Storybook found** → go to [Fresh Setup Workflow](#fresh-setup-workflow)

---

## Fresh Setup Workflow

### 1. Detect ecosystem integration

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.

### 2. Detect UI framework

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 |

### 3. Set up Storybook

1. In monorepos, operate in the package that will host stories
2. Read and follow the framework guide matched above; install the **latest stable** `storybook` major and the matching `storybook-<framework>-rsbuild` major (Principle 2)
3. Add `@rsbuild/core` to `devDependencies` directly, alongside `storybook-<framework>-rsbuild` (Principle 3)
4. Ensure `.storybook/main.*` uses the correct `framework: '<storybook-*-rsbuild>'`
5. Ensure `package.json` has `storybook dev` and `storybook build` scripts
6. If no story file exists yet, scaffold at least one minimal example story (e.g. `src/stories/Example.stories.*`) so [Verification](#verification) step 2 has something to render
7. Run [Verification](#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. 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)
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 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
7. **Verify, then clean up — both required** — run [Verification](#verification) below; once it passes, in the same task complete all