Skip to main content
skill CX Codex

storybook-rsbuild — Claude Code skill for Storybook setup

The storybook-rsbuild skill sets up Storybook with Rsbuild or migrates an existing project from webpack or Vite. It also handles integrations with Rslib, Modern.js, and Rspack.

MIT 212 installs ★ 100 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rstackjs/agent-skills --skill storybook-rsbuild -a claude-code
Open on GitHub

What storybook-rsbuild does

The skill checks the project structure and package.json to identify the current Storybook setup and UI framework. It then guides a fresh setup or a move to Rsbuild, including the framework package, .storybook/main.*, and the storybook dev and storybook build scripts.

During migration, it keeps the old packages and configuration until verification succeeds, then removes the previous builder and its related config blocks. Webpack-specific addons need to pass through webpackAddons or be replaced with Rsbuild configuration. In a monorepo, changes stay in the package that hosts the stories.

The skill consults storybook.rsbuild.rs for version requirements and setup instructions, so network access is required. Without it, the agent cannot check the framework's current compatibility guidance.

What it helps with

  • set up Storybook on Rsbuild for the project's UI framework
  • move an existing Storybook setup from webpack or Vite
  • update .storybook/main.* for Rsbuild
  • preserve webpack addons during migration

Example prompts for the agent

  • Set up Storybook with Rsbuild for React in this project.
  • Move this project's Storybook from Vite to Rsbuild, then verify the setup.
  • Check the Storybook integration for Rslib in this monorepo.

How to install storybook-rsbuild

1Skills CLI (Vercel)

npx skills add rstackjs/agent-skills --skill storybook-rsbuild -a claude-code

2Manually: put the files in place

~/.claude/skills/storybook-rsbuild/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/storybook-rsbuild/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about storybook-rsbuild

How do I install storybook-rsbuild in Claude Code?

Run npx skills add rstackjs/agent-skills --skill storybook-rsbuild -a claude-code. The skill file will be at ~/.claude/skills/storybook-rsbuild/SKILL.md.

What does storybook-rsbuild do?

It guides a fresh Storybook setup on Rsbuild or a migration from webpack or Vite. It also covers integrations with Rslib, Modern.js, and Rspack.

Does storybook-rsbuild need network access?

Yes. It reads storybook.rsbuild.rs for version compatibility and setup guidance.

Source text

SKILL.md · MIT
---
name: storybook-rsbuild
description: Set up or migrate Storybook to Rsbuild, configure rsbuildFinal, or integrate with Rslib, Modern.js, or Rspack.
compatibility: Requires network access to read upstream docs at storybook.rsbuild.rs
---

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

---

## Verification

1. `storybook dev` starts without errors
2. 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)
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

© rstackjs · MIT · rstackjs/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set21

The whole set →
rspress-docs-generator rspress-docs-generator builds a new Rspress v2 docs site or updates existing documentation pages according to changes in source code and tests. CX Codex +1 344installs migrate-to-rsbuild migrate-to-rsbuild — a skill that migrates webpack, Vite, Create React App, and Vue CLI projects to Rsbuild. It rewrites build configs and validates dev servers before cleaning up old packages. CX Codex +1 342installs rspack-tracing rspack-tracing — a skill for Claude Code and other IDEs that captures and analyzes Rspack build traces to pinpoint slow compiler phases, plugins, and loaders. Diagnose performance bottlenecks and crashes during development. CX Codex +1 291installs rspack-debugging rspack-debugging captures the crash state of native Rspack with LLDB: backtraces for segfaults, deadlocks and builds that hang. Useful when the failure sits inside Rust. CX Codex +1 282installs migrate-to-rslib migrate-to-rslib converts TypeScript library builds from tsc or tsup to Rslib with validation before cleanup. CX Codex +1 201installs rspack-split-chunks rspack-split-chunks teaches the agent to diagnose and tune optimization.splitChunks in Rspack: find duplicate modules, over-fetching, cache group issues, and oversized chunks. CX Codex +1 187installs rspress-v2-upgrade The rspress-v2-upgrade skill automates upgrading an Rspress project from v1 to v2. It reads the config, updates dependencies, rewrites import paths, and validates the build against the official migration guide. CX Codex +1 150installs rstest-debugging rstest-debugging diagnoses Rstest startup, build, runtime, logging, memory, and performance issues with traces and comparable measurements. CX Codex +1 133installs

Project sponsors

Companies that keep this analytics open