---
url: /guide/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Getting started

![Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild/assets/7237365/00165054-9e3e-4a15-8a99-27985989b9d2)


[![latest version](https://img.shields.io/npm/v/storybook-builder-rsbuild?style=flat-square&color=ff4785)](https://www.npmjs.com/package/storybook-builder-rsbuild)[![NPM downloads per month](https://img.shields.io/npm/dm/storybook-builder-rsbuild?style=flat-square&color=%23ff4785)](https://npmcharts.com/compare/storybook-builder-rsbuild,storybook-react-rsbuild,storybook-react-vue,storybook-vue3-rsbuild,storybook-vue3-rsbuild?interval=7&log=false)[![license](https://img.shields.io/npm/l/storybook-builder-rsbuild?style=flat-square&color=%23ff4785)](https://github.com/rstackjs/storybook-rsbuild/blob/main/LICENSE)


:::info Storybook versions

The `main` branch ships the Storybook v10 Rsbuild builder together with each framework integration. Use the table below to match your Storybook version, and review the [official migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-9x-to-1000) before moving to v10.

| Storybook | Storybook Rsbuild                                               |
| --------- | --------------------------------------------------------------- |
| v10       | [^3.0.0](https://github.com/rstackjs/storybook-rsbuild)         |
| v9        | [^2.0.0](https://github.com/rstackjs/storybook-rsbuild/tree/v2) |
| v8        | [^1.0.0](https://github.com/rstackjs/storybook-rsbuild/tree/v1) |

:::

Storybook Rsbuild allows you to use [Rsbuild](https://rsbuild.rs) as the build engine for Storybook, providing faster startup and build times.

:::tip Using an AI coding agent?
If you use [Claude Code](https://code.claude.com), [Codex](https://openai.com/codex), [OpenCode](https://opencode.ai), or other AI coding agents, install our agent skills for guided setup and migration:


```sh [npx]
npx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [bunx]
bunx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill storybook-rsbuild
```

The skills teach your agent how to configure `rsbuildFinal`, set up framework integrations, and migrate from webpack/Vite.
:::

## Quick Start

The fastest way to get started is using the Storybook CLI.

### New Project

If you are setting up a new project, we recommend creating an Rsbuild project first, then adding Storybook.

```bash
# 1. Create a new Rsbuild project
npm create rsbuild@latest

# 2. Initialize Storybook (in the project root)
npx storybook@latest init
```

Storybook will detect Rsbuild and automatically configure `storybook-builder-rsbuild` for you. It will also add example stories to your project. To understand the generated files, check the [Storybook Project Structure](https://storybook.js.org/docs/configure/user-interface/sidebar-and-urls).

### Existing Project

If you are migrating an existing Storybook project to Rsbuild, install the relevant framework package and update your `.storybook/main.ts`.

:::tip Reuse your existing Rsbuild config
If the project already has an `rsbuild.config.ts` in the directory where Storybook runs, Storybook Rsbuild detects and merges it into the preview build automatically. You do not need to duplicate its plugins or aliases in `rsbuildFinal`; for a config elsewhere, set the builder option `rsbuildConfigPath`.
:::

See the **[Frameworks](/guide/framework/react.md)** section for detailed migration guides.

## Packages

| Package                                                                                                                       | What it provides                                           |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [storybook-builder-rsbuild](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/builder-rsbuild)                 | The Rsbuild-powered Storybook builder                      |
| [storybook-react-rsbuild](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-react)                   | React framework integration configured for Rsbuild         |
| [storybook-vue3-rsbuild](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-vue3)                     | Vue 3 framework integration configured for Rsbuild         |
| [storybook-html-rsbuild](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-html)                     | Vanilla JavaScript/TypeScript integration                  |
| [storybook-web-components-rsbuild](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-web-components) | Lit and Web Components integration                         |
| [storybook-addon-rslib](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/addon-rslib)                         | Addon that reuses Rslib configuration inside Storybook     |
| [storybook-addon-rstack](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/addon-rstack)                       | Addon that reuses Rstack configuration inside Storybook    |
| [storybook-addon-modernjs](https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/addon-modernjs)                   | Addon that reuses Modern.js configuration inside Storybook |

## Usage

:::info Peer dependency requirements

**`@rsbuild/core`**
 `^1.5.0 || ^2.0.0-0` — Storybook Rsbuild requires the stable Rsbuild runtime. See the [1.0 release announcement](https://rsbuild.rs/community/releases/v1-0)
 for background.
**`storybook`**
 `^10.6.0` — The range is pinned to the `storybook`
 peer of the bundled `@storybook/*`
 packages and is bumped alongside Storybook releases. Starting with v3.6.0, the minor version of Storybook Rsbuild tracks the Storybook minor it is built against: 3.6.x targets Storybook 10.6, 3.7.x will target Storybook 10.7, and so on. Upgrade guidance is available in the [Storybook release notes](https://storybook.js.org/blog/storybook-10/)
.
:::

When using the v8-compatible packages, you do not install `storybook-builder-rsbuild` directly. Framework packages such as `storybook-react-rsbuild` and `storybook-vue3-rsbuild` include it for you.

Use the following framework guides to plug Storybook Rsbuild into your project.

## Use with frameworks

### React

See [integrating with React](/guide/framework/react.md).

### Vue

See [integrating with Vue](/guide/framework/vue.md).

### Vanilla JS/TS

See [integrating with vanilla JavaScript / TypeScript](/guide/framework/vanilla.md).

### Web components

See [integrating with web components (Lit)](/guide/framework/web-components.md).

## Integration

### With Modern.js

Use your existing Modern.js configuration inside Storybook.

See [integrating with Modern.js](/guide/integrations/modernjs.md).

### With Rslib

Reuse your existing Rslib configuration inside Storybook.

See [integrating with Rslib](/guide/integrations/rslib.md).

### With Rstack

Reuse an app or library definition from your Rstack configuration inside Storybook.

See [integrating with Rstack](/guide/integrations/rstack.md).

### With Rspack

Connect Storybook Rsbuild to an existing Rspack setup.

See [integrating with Rspack](/guide/integrations/rspack.md).



---
url: /guide/configuration.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Configuration

Storybook Rsbuild provides several ways to customize the build process and behavior. This guide covers the configuration options available in your `.storybook/main.ts`.

:::tip Storybook Documentation
This guide focuses on Rsbuild-specific configurations. For general Storybook configuration (stories, addons, refs, etc.), please refer to the [Storybook Configure](https://storybook.js.org/docs/configure) documentation.
:::

## rsbuildFinal

The `rsbuildFinal` field gives you direct access to the Rsbuild configuration. You can use it to customize the build config, similar to [webpackFinal](https://storybook.js.org/docs/builders/webpack#extending-storybooks-webpack-config) in the Webpack builder.

This function receives the current Rsbuild config and an options object, and should return the modified config.

:::warning Use `mergeRsbuildConfig` for modifications
Always use [`mergeRsbuildConfig`](https://rsbuild.rs/api/javascript-api/core#mergersbuildconfig) from `@rsbuild/core` to modify the config in `rsbuildFinal`; returning a brand-new config is unsupported. Directly replacing properties like `config.tools.rspack = {...}` may also be silently ignored because internal configs can be arrays of functions and objects. Inside the function form of `tools.rspack`, modify and return the provided config or use the callback's `mergeConfig` utility; returning a brand-new object silently drops Storybook-injected wiring such as the `sb.mock` machinery.
:::

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [],
  async rsbuildFinal(config, { configType }) {
    // Customize Rsbuild config here
    if (configType === 'PRODUCTION') {
      return mergeRsbuildConfig(config, {
        performance: {
          removeConsole: true,
        },
      })
    }

    // Example: add resolve alias
    return mergeRsbuildConfig(config, {
      resolve: {
        alias: {
          '@components': './src/components',
        },
      },
    })
  },
}

export default config
```

## Builder Options

You can configure the underlying Rsbuild builder through the `core.builder` options.

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: [],
  core: {
    builder: {
      name: 'storybook-builder-rsbuild',
      options: {
        // Path to your existing rsbuild.config.ts
        // Defaults to the root rsbuild.config.ts if found
        rsbuildConfigPath: './custom-rsbuild.config.ts',

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

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

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

export default config
```

### Inherited Rsbuild Configuration

The config selected by `rsbuildConfigPath` is automatically merged into the Storybook preview build. Production-only settings can affect or break the preview, so the following fields are not inherited:

- `source.entry`
- `output.distPath`, `output.filename`, `output.cleanDistPath`, `output.externals`, and `output.assetPrefix`
- `server.publicDir`
- `dev.progressBar`, `dev.assetPrefix`, and `dev.writeToDisk`
- `tools.htmlPlugin`
- `tools.rspack.output.library`, `tools.rspack.output.globalObject`, and `tools.rspack.output.umdNamedDefine`

This boundary also applies to configuration inherited by `storybook-addon-rslib`, `storybook-addon-rstack`, and `storybook-addon-modernjs`. Function-form `tools.rspack` values are opaque and cannot be stripped. Prefer a dedicated [Rsbuild environment](https://rsbuild.rs/config/environments) selected with `environment` to isolate Storybook-safe settings. To restore a stripped field intentionally, add it explicitly in Storybook's `rsbuildFinal`; explicit configuration runs after inherited configuration is stripped.

Plugins remain inherited because they commonly provide transforms required by the preview build. The Storybook CLI sets `process.env.STORYBOOK` to `'true'` before loading project configuration, so use that condition to omit an app-only plugin that should not run in Storybook.

### Option Reference

| Option              | Type                                                                               | Default                                                  | Description                                                                                                            |
| :------------------ | :--------------------------------------------------------------------------------- | :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| `rsbuildConfigPath` | `string`                                                                           | `cwd/rsbuild.config.ts`                                  | Path to an existing Rsbuild config file to merge.                                                                      |
| `fsCache`           | `boolean`                                                                          | `false`                                                  | Enables Rspack's persistent filesystem cache.                                                                          |
| `lazyCompilation`   | `boolean` \| [`LazyCompilationOptions`](https://rspack.rs/config/lazy-compilation) | `{ entries: false }` (development); `false` (production) | Configures Rspack's lazy compilation.                                                                                  |
| `environment`       | `string`                                                                           | `undefined`                                              | Selects an [environment](https://rsbuild.rs/config/environments) from the Rsbuild config; an explicit name must exist. |

When `environment` is omitted, zero environments uses top-level config, one is selected automatically, and multiple environments require a name.

In development, the default `{ entries: false }` compiles entry chunks eagerly while lazily compiling dynamically imported story modules. In production, this builder option is not applied, so lazy compilation remains off by default; lower-level Rsbuild or Rspack configuration can override that behavior. In development, automatic MSW detection also changes the default to `false` unless you explicitly configure this option. This differs from the Storybook webpack builder, where lazy compilation is opt-in and remains off unless enabled.

## Webpack Addons Compatibility

Since Rspack is compatible with the webpack loader/plugin API, you can often use Storybook addons designed for Webpack. To do this, use the `webpackAddons` field instead of `addons`.

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

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

export default config
```

## Framework Options

Framework-specific options allow you to tailor the behavior for React, Vue, etc.

### React Options

For `storybook-react-rsbuild`, you can configure `reactDocgen` and legacy root API.

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: {
    name: 'storybook-react-rsbuild',
    options: {
      // Configure strict mode
      strictMode: true,

      // Use legacy ReactDOM.render instead of createRoot (React 18+)
      legacyRootApi: false,
    },
  },
  stories: [],
  typescript: {
    // Configure docgen for TypeScript
    // 'react-docgen-typescript' | 'react-docgen' | false
    reactDocgen: 'react-docgen-typescript',

    // Pass options to react-docgen-typescript-plugin
    reactDocgenTypescriptOptions: {
      propFilter: (prop) => {
        return prop.parent ? !/node_modules/.test(prop.parent.fileName) : true
      },
    },
  },
}

export default config
```

## TypeScript Options

Storybook Rsbuild uses `@rsbuild/plugin-type-check` for type checking. You can configure it via the `typescript` field.

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: [],
  typescript: {
    // Enable/disable fork-ts-checker-webpack-plugin
    check: true,

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

export default config
```

See [Storybook TypeScript Docs](https://storybook.js.org/docs/configure/integration/typescript) for general TypeScript configuration.

## Preview Output Layout

`storybook build` emits the preview with a flat layout — bundled JS and CSS land directly in the output directory (`storybook-static` by default), the same as the official webpack5 builder:

```text
storybook-static/
├── iframe.html
├── main.<hash>.iframe.bundle.js
├── <chunk-id>.<hash>.iframe.bundle.js
├── <entry>.<hash>.css
├── <name>.<hash>.svg      # imported SVGs and WebAssembly also land at the root
└── static/media/          # imported images, fonts, and media
```

Versions before v3.4.0 nested these files under `static/js/`, `static/js/async/`, and `static/css/`.



---
url: /guide/examples.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Examples

Storybook Rsbuild provides a variety of examples (sandboxes) to help you get started with different frameworks and configurations.

These examples are located in the [`sandboxes`](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes) directory of the repository.

## Frameworks

### React

- **[React 18](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/react-18)**: Basic React 18 setup with TypeScript.
- **[React 16](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/react-16)**: Legacy React 16 support.
- **[Rspack React](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rspack-react-18)**: Integration with raw Rspack configuration (without Rsbuild).

### Vue

- **[Vue 3](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/vue3)**: Vue 3 with TypeScript and JSX support.

### Web Components

- **[Lit](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/lit)**: Web Components development using Lit.

### Vanilla JS/TS

- **[Vanilla TS](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/vanilla-ts)**: Framework-agnostic setup for vanilla JavaScript/TypeScript.

## Advanced Integrations

### Module Federation

Storybook Rsbuild supports [Module Federation](https://module-federation.io/) out of the box.

- **[Modern.js Module Federation](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react-mf)**: A host application loading federated modules from a remote, all running within Storybook.
- **[Rslib Module Federation](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rslib-react-mf)**: Developing a federated component library with Rslib and Storybook.

### Modern.js

- **[Modern.js Framework](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react)**: Seamless integration with the Modern.js full-stack framework, reusing the app's config.

### Rslib (Library Build)

- **[Rslib Component Library](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rslib-react-component)**: Developing a React component library with Rslib, demonstrating how to reuse Rslib config for Storybook.
- **[Rslib Vue Component](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rslib-vue3-component)**: Developing a Vue 3 component library with Rslib.

### Rstack

- **[Rstack React App](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rstack-react)**: Developing a React app while reusing an async `define.app()` configuration from Rstack.
- **[Rstack React Component](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rstack-react-component)**: Developing a React component library while reusing an async `define.lib()` configuration from Rstack.

## Testing

- **[React Testing](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/react-testing)**: Demonstrates Storybook's test runner and interaction testing capabilities.



---
url: /guide/framework.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Framework

Storybook supports many frontend stacks—React, Vue, Web Components, and more. Use this section to learn how to add or extend framework support when working with Storybook Rsbuild.

:::info
For detailed contribution guidance, see [Contributing a Storybook framework](https://storybook.js.org/docs/contribute/framework).
:::

## Supported frameworks

| Framework          | Documentation                                      | Source                                                                                                 | npm package                                                  |
| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| React              | [Framework - React](/guide/framework/react.md)     | <SourceCode href="https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-react" /> | [npm](https://www.npmjs.com/package/storybook-react-rsbuild) |
| Vue 3              | [Framework - Vue 3](/guide/framework/vue.md)       | <SourceCode href="https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-vue3" />  | [npm](https://www.npmjs.com/package/storybook-vue3-rsbuild)  |
| Vanilla JavaScript | [Framework - Vanilla](/guide/framework/vanilla.md) | <SourceCode href="https://github.com/rstackjs/storybook-rsbuild/tree/main/packages/framework-html" />  | [npm](https://www.npmjs.com/package/storybook-html-rsbuild)  |



---
url: /guide/framework/react.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# React

Storybook for React & Rsbuild lets you develop and test React components in isolation using the Rsbuild toolchain your app already relies on.

## Requirements


| Package | Version |
| --- | --- |
| `react` | ≥ 16.8 |
| `@rsbuild/core` | `^1.5.0 \|\| ^2.0.0-0` |
| `storybook` | `^10.6.0` |


## Getting started

Follow these steps inside an existing Rsbuild-powered React project.

### Installation

Install the framework package and `@rsbuild/core`. Even though `storybook-react-rsbuild` declares `@rsbuild/core` as a peer, list it as a direct dev dependency so version pins and lockfile audits remain unambiguous.


```sh [npm]
npm install @rsbuild/core storybook-react-rsbuild -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-react-rsbuild -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-react-rsbuild -D
```

```sh [bun]
bun add @rsbuild/core storybook-react-rsbuild -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-react-rsbuild -D
```

### Configure `.storybook/main.ts`

```js
import { StorybookConfig } from 'storybook-react-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  rsbuildFinal: (config) => {
    // Customize the final Rsbuild config here
    return mergeRsbuildConfig(config, {
      // your custom config
    })
  },
}

export default config
```

That's it! Explore the [React 16](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/react-16) and [React 18](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/react-18) sandboxes for full examples, and continue learning from the [Storybook documentation](https://storybook.js.org/docs).

## Next Steps

Now that you've set up the build system, learn how to write stories and document your components:

- **[Writing Stories](https://storybook.js.org/docs/writing-stories)**: Learn the basics of Component Story Format (CSF).
- **[Auto-docs](https://storybook.js.org/docs/writing-docs/autodocs)**: Automatically generate documentation from your components.

## Options

Please refer to the [Configuration Guide](/guide/configuration.md#framework-options) for framework-specific options and defaults.



---
url: /guide/framework/react-native-web.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# React Native Web

Storybook for React Native Web & Rsbuild enables you to develop and document React Native components that run on the web using [react-native-web](https://necolas.github.io/react-native-web/).

This framework extends `storybook-react-rsbuild` to provide full React Native Web compatibility, including alias resolution, web-specific extensions, and transpilation of React Native packages.

## Requirements


| Package | Version |
| --- | --- |
| `react` | ≥ 16.8 |
| `react-native-web` | `^0.19.0 \|\| ^0.20.0 \|\| ^0.21.0` |
| `@rsbuild/core` | `^1.5.0 \|\| ^2.0.0-0` |
| `@rsbuild/plugin-react` | ≥ 1.0.0 |
| `storybook` | `^10.6.0` |


## Getting started

### Installation

Install the framework package and its peer dependencies. Both `@rsbuild/core` and `@rsbuild/plugin-react` are listed directly so version pins and lockfile audits remain unambiguous.


```sh [npm]
npm install @rsbuild/core @rsbuild/plugin-react storybook-react-native-web-rsbuild react-native-web -D
```

```sh [yarn]
yarn add @rsbuild/core @rsbuild/plugin-react storybook-react-native-web-rsbuild react-native-web -D
```

```sh [pnpm]
pnpm add @rsbuild/core @rsbuild/plugin-react storybook-react-native-web-rsbuild react-native-web -D
```

```sh [bun]
bun add @rsbuild/core @rsbuild/plugin-react storybook-react-native-web-rsbuild react-native-web -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:@rsbuild/plugin-react npm:storybook-react-native-web-rsbuild npm:react-native-web -D
```

### Configure `rsbuild.config.ts`

Create or update your Rsbuild configuration to include the React plugin:

```ts
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'

export default defineConfig({
  plugins: [pluginReact()],
})
```

### Configure `.storybook/main.ts`

```ts
import type { StorybookConfig } from 'storybook-react-native-web-rsbuild'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  framework: {
    name: 'storybook-react-native-web-rsbuild',
    options: {},
  },
}

export default config
```

## Features

The framework automatically handles:

- **Alias resolution**: `react-native` → `react-native-web`
- **Web extensions**: Prioritizes `.web.tsx`, `.web.ts`, `.web.js` files
- **Global definitions**: Sets up `__DEV__`, `EXPO_OS`, and other React Native globals
- **Package transpilation**: Transpiles `react-native`, `@react-native`, `expo`, and `@expo` packages
- **React docgen**: Full support for props documentation via react-docgen

## Framework Options

```ts
interface FrameworkOptions {
  /**
   * Additional node_modules that need to be transpiled.
   * Packages starting with `react-native`, `@react-native`, `expo`, and `@expo`
   * are included by default.
   */
  modulesToTranspile?: string[]

  /**
   * Options passed to the underlying rsbuild-plugin-react-native-web plugin.
   */
  pluginOptions?: PluginReactNativeWebOptions
}

interface PluginReactNativeWebOptions {
  /**
   * Additional node_modules that need to be transpiled.
   * @example ['my-react-native-library']
   */
  modulesToTranspile?: string[]

  /**
   * The JSX runtime to use.
   * @default 'automatic'
   */
  jsxRuntime?: 'automatic' | 'classic'

  /**
   * The source for JSX imports when using the automatic runtime.
   * @default 'react'
   * @example 'nativewind' for NativeWind v4+
   */
  jsxImportSource?: string

  /**
   * Modules that should not be tree-shaken.
   * @default ['react-native-css-interop', 'expo-modules-core']
   */
  noTreeshakeModules?: string[]
}
```

### Example: Transpiling additional packages

Some React Native libraries ship untranspiled code. Add them to `modulesToTranspile`:

```ts
const config: StorybookConfig = {
  framework: {
    name: 'storybook-react-native-web-rsbuild',
    options: {
      modulesToTranspile: [
        'react-native-reanimated',
        '@react-navigation/native',
      ],
    },
  },
}
```

## Writing Stories

Write stories using standard React Native components:

```tsx
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
}

export default meta
type Story = StoryObj<typeof Button>

export const Primary: Story = {
  args: {
    label: 'Press me',
    variant: 'primary',
  },
}
```

```tsx
// Button.tsx
import { Text, TouchableOpacity, StyleSheet } from 'react-native'

export function Button({ label, onPress, variant = 'primary' }) {
  return (
    <TouchableOpacity
      onPress={onPress}
      style={[styles.button, styles[variant]]}
    >
      <Text style={styles.text}>{label}</Text>
    </TouchableOpacity>
  )
}

const styles = StyleSheet.create({
  button: {
    paddingVertical: 12,
    paddingHorizontal: 20,
    borderRadius: 8,
  },
  primary: {
    backgroundColor: '#007AFF',
  },
  text: {
    color: 'white',
    fontWeight: 'bold',
  },
})
```

## NativeWind Support

This framework supports [NativeWind](https://www.nativewind.dev/) for using Tailwind CSS with React Native components.

### Installation


```sh [npm]
npm install nativewind react-native-css-interop react-native-safe-area-context tailwindcss postcss autoprefixer -D
```

```sh [yarn]
yarn add nativewind react-native-css-interop react-native-safe-area-context tailwindcss postcss autoprefixer -D
```

```sh [pnpm]
pnpm add nativewind react-native-css-interop react-native-safe-area-context tailwindcss postcss autoprefixer -D
```

```sh [bun]
bun add nativewind react-native-css-interop react-native-safe-area-context tailwindcss postcss autoprefixer -D
```

```sh [deno]
deno add npm:nativewind npm:react-native-css-interop npm:react-native-safe-area-context npm:tailwindcss npm:postcss npm:autoprefixer -D
```

:::tip
Installing `react-native-safe-area-context` is recommended to avoid build warnings from `react-native-css-interop`.
:::

### Configuration

1. **Configure Tailwind CSS** - Create `tailwind.config.js`:

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  presets: [require('nativewind/preset')],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

2. **Create global CSS** - Create `src/global.css`:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

3. **Import CSS in preview** - Update `.storybook/preview.tsx`:

```tsx
import '../src/global.css'

const preview = {
  // your preview config
}

export default preview
```

4. **Configure JSX import source** - Update `.storybook/main.ts`:

```ts
const config: StorybookConfig = {
  framework: {
    name: 'storybook-react-native-web-rsbuild',
    options: {
      pluginOptions: {
        jsxImportSource: 'nativewind',
      },
    },
  },
}
```

### Usage

```tsx
import { View, Text } from 'react-native'

export function Card({ title, children }) {
  return (
    <View className="p-4 bg-white rounded-lg shadow-md">
      <Text className="text-xl font-bold text-gray-800">{title}</Text>
      {children}
    </View>
  )
}
```

## React Native Reanimated

This framework provides built-in support for [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) on web.

### Installation


```sh [npm]
npm install react-native-reanimated react-native-worklets
```

```sh [yarn]
yarn add react-native-reanimated react-native-worklets
```

```sh [pnpm]
pnpm add react-native-reanimated react-native-worklets
```

```sh [bun]
bun add react-native-reanimated react-native-worklets
```

```sh [deno]
deno add npm:react-native-reanimated npm:react-native-worklets
```

:::info pnpm hoisting
With pnpm's default hoisting (`hoistPattern: ['*']`), nothing extra is needed. If your project sets `hoist: false` or a restricted `hoistPattern` in `pnpm-workspace.yaml`, add `react-native-web` to `hoistPattern`: `react-native-reanimated` 4 imports `react-native-web` internals (such as `react-native-web/dist/cjs/...`) without declaring `react-native-web` as a dependency, so without hoisting those imports fail to resolve in pnpm's isolated `node_modules`.

```yaml
# pnpm-workspace.yaml
hoistPattern:
  - react-native-web
```

:::

### What the framework handles

The framework automatically:

- Defines `_WORKLET` and `_frameTimestamp` globals required by Reanimated
- Transforms Reanimated's webUtils for ESM compatibility
- Handles module resolution in pnpm/monorepo environments

### Usage

```tsx
import Animated, { FadeIn, FadeOut } from 'react-native-reanimated'

export function FadeInView({ children }) {
  return (
    <Animated.View entering={FadeIn.duration(500)} exiting={FadeOut}>
      {children}
    </Animated.View>
  )
}
```

## Expo Support

This framework works with Expo projects. Ensure your `metro.config.js` or bundler configuration is not conflicting with Rsbuild.

For Expo-specific globals, the plugin automatically defines:

- `EXPO_OS` → `'web'`
- `process.env.EXPO_OS` → `'web'`

## Next Steps

- **[React Native Web Documentation](https://necolas.github.io/react-native-web/)**: Learn about supported APIs
- **[Writing Stories](https://storybook.js.org/docs/writing-stories)**: Learn the basics of Component Story Format (CSF)
- **[Example Sandbox](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/react-native-web)**: See a working example

## Troubleshooting

### "React is not defined" error

Make sure you have `@rsbuild/plugin-react` installed and configured in `rsbuild.config.ts`. This plugin enables the automatic JSX runtime.

### Module not found errors for React Native packages

Add the problematic package to `modulesToTranspile` in your framework options.

### TypeScript errors for `react-native` imports

Install `@types/react-native` as a dev dependency, or create a `react-native.d.ts` file:

```ts
declare module 'react-native' {
  export * from 'react-native-web'
}
```

### Flow syntax errors in React Native packages

Some older React Native packages may contain [Flow](https://flow.org/) type annotations that are not stripped before publishing. If you encounter syntax errors related to Flow types (e.g., `Unexpected token :` in type annotations), you can use Babel to strip Flow types.

1. Install the required packages:

```bash
pnpm add -D @babel/core babel-loader @babel/preset-flow @babel/preset-react
```

2. Add a custom Rsbuild configuration in `.storybook/main.ts`:

```ts
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: {
    name: 'storybook-react-native-web-rsbuild',
    options: {},
  },
  rsbuildFinal: async (config) => {
    return mergeRsbuildConfig(config, {
      tools: {
        bundlerChain: (chain) => {
          // Add babel-loader for packages with Flow syntax
          chain.module
            .rule('flow')
            .test(/\.jsx?$/)
            .include.add(/node_modules\/(react-native|@react-native)/)
            .end()
            .use('babel')
            .loader('babel-loader')
            .options({
              presets: ['@babel/preset-flow', '@babel/preset-react'],
            })
        },
      },
    })
  },
}
```

This configuration uses Babel to process React Native packages and strip Flow type annotations before they are handled by SWC.



---
url: /guide/framework/vue.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Vue

Storybook for Vue & Rsbuild helps you preview and iterate on Vue components with the same Rsbuild configuration you use for your application.

## Requirements


| Package | Version |
| --- | --- |
| `vue` | ≥ 3 |
| `@rsbuild/core` | `^1.5.0 \|\| ^2.0.0-0` |
| `storybook` | `^10.6.0` |


## Getting started

Use the steps below in an existing Rsbuild-based Vue project.

### Installation

Install the Vue framework package and `@rsbuild/core`. Even though `storybook-vue3-rsbuild` declares `@rsbuild/core` as a peer, list it as a direct dev dependency so version pins and lockfile audits remain unambiguous.


```sh [npm]
npm install @rsbuild/core storybook-vue3-rsbuild -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-vue3-rsbuild -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-vue3-rsbuild -D
```

```sh [bun]
bun add @rsbuild/core storybook-vue3-rsbuild -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-vue3-rsbuild -D
```

### Configure `.storybook/main.ts`

```js
import { StorybookConfig } from 'storybook-vue3-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-vue3-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  rsbuildFinal: (config) => {
    // Customize the final Rsbuild config here
    return mergeRsbuildConfig(config, {
      // your custom config
    })
  },
}

export default config
```

You're ready to go! Check the [Vue 3 sandbox](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/vue3) for a complete reference, and explore the [Storybook docs](https://storybook.js.org/docs) for feature guides.

## Next Steps

Now that Storybook is running, explore how to create stories for your Vue components:

- **[Writing Stories](https://storybook.js.org/docs/writing-stories)**: Learn the Component Story Format (CSF).
- **[Vue Essentials](https://storybook.js.org/docs/get-started/frameworks/vue3-vite)**: Specific guides for Vue development in Storybook.

## Options

Please refer to the [Configuration Guide](/guide/configuration.md#framework-options) for framework-specific options and defaults.



---
url: /guide/framework/web-components.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Web Components

Storybook for Web Components & Rsbuild is tailored for Lit and custom-element projects, giving you fast component previews without leaving your Rsbuild workflow.

## Requirements


| Package | Version |
| --- | --- |
| `lit` | ≥ 2 (or ≥ 3) |
| `@rsbuild/core` | `^1.5.0 \|\| ^2.0.0-0` |
| `storybook` | `^10.6.0` |


## Getting started

Run through these steps inside an Rsbuild project that renders Web Components.

### Installation

Install the Web Components framework package and `@rsbuild/core`. Even though `storybook-web-components-rsbuild` declares `@rsbuild/core` as a peer, list it as a direct dev dependency so version pins and lockfile audits remain unambiguous.


```sh [npm]
npm install @rsbuild/core storybook-web-components-rsbuild -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-web-components-rsbuild -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-web-components-rsbuild -D
```

```sh [bun]
bun add @rsbuild/core storybook-web-components-rsbuild -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-web-components-rsbuild -D
```

### Configure `.storybook/main.ts`

```js
import { StorybookConfig } from 'storybook-web-components-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-web-components-rsbuild',
  stories: ['../src/**/*.stories.@(js|mjs|ts)'],
  rsbuildFinal: (config) => {
    // Customize the final Rsbuild config here
    return mergeRsbuildConfig(config, {
      // your custom config
    })
  },
}

export default config
```

You're good to go! See the [web components sandbox](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/lit) for a complete reference and browse the [Storybook docs](https://storybook.js.org/docs) for deeper guidance.

## Next Steps

- **[Writing Stories](https://storybook.js.org/docs/writing-stories)**: Learn the basics of CSF for Web Components.
- **[Lit Snippets](https://storybook.js.org/docs/get-started/frameworks/web-components-vite)**: Examples using Lit and generic Web Components.

## Options

Please refer to the [Configuration Guide](/guide/configuration.md#framework-options) for framework-specific options and defaults.



---
url: /guide/framework/vanilla.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Vanilla JS / TS

Use Storybook for vanilla JavaScript or TypeScript projects to preview UI components while keeping your Rsbuild pipeline intact.

## Requirements


| Package | Version |
| --- | --- |
| `@rsbuild/core` | `^1.5.0 \|\| ^2.0.0-0` |
| `storybook` | `^10.6.0` |


## Getting started

These steps assume you already have an Rsbuild project without a specific framework.

### Installation

Install the HTML framework package and `@rsbuild/core`. Even though `storybook-html-rsbuild` declares `@rsbuild/core` as a peer, list it as a direct dev dependency so version pins and lockfile audits remain unambiguous.


```sh [npm]
npm install @rsbuild/core storybook-html-rsbuild -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-html-rsbuild -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-html-rsbuild -D
```

```sh [bun]
bun add @rsbuild/core storybook-html-rsbuild -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-html-rsbuild -D
```

### Configure `.storybook/main.ts`

```js
import { StorybookConfig } from 'storybook-html-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-html-rsbuild',
  stories: ['../src/**/*.stories.@(js|mjs|ts)'],
  rsbuildFinal: (config) => {
    // Customize the final Rsbuild config here
    return mergeRsbuildConfig(config, {
      // your custom config
    })
  },
}

export default config
```

You're all set! Review the [vanilla TypeScript sandbox](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/vanilla-ts) to see the setup in action, and continue exploring the [Storybook docs](https://storybook.js.org/docs).

## Next Steps

- **[Writing Stories](https://storybook.js.org/docs/writing-stories)**: Learn how to write stories for vanilla JavaScript/TypeScript.
- **[Testing](https://storybook.js.org/docs/writing-tests)**: Learn how to test your UI components.

## Options

Please refer to the [Configuration Guide](/guide/configuration.md#framework-options) for framework-specific options and defaults.



---
url: /guide/integrations/modernjs.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Modern.js

This addon loads a reusable Rsbuild config from your Modern.js configuration file so `storybook-builder-rsbuild` reuses the same settings your application already trusts.

## Getting started

Explore the [Modern.js React example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to see the integration in a real project.

### Installation


```sh [npm]
npm install @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [bun]
bun add @rsbuild/core storybook-react-rsbuild storybook-addon-modernjs -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-react-rsbuild npm:storybook-addon-modernjs -D
```

Install the React framework package and `@rsbuild/core` in the same workspace. The configuration below uses `storybook-react-rsbuild` as the framework, and the addon needs `@rsbuild/core` to read your Modern.js configuration.

Match the version used by `@modern-js/app-tools` when possible. If you install a different release, `storybook-addon-modernjs` prints a warning with the recommended version.

### Setup `.storybook/main.ts`

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['storybook-addon-modernjs'],
  framework: 'storybook-react-rsbuild',
}
export default config
```

Before the resolved Modern.js config is merged into Storybook, it passes through the inherited-config boundary documented in [Builder Options](/guide/configuration.md#builder-options). To restore a stripped field intentionally, add it in Storybook's `rsbuildFinal`; explicit configuration runs after inherited fields are stripped. Of a Modern.js `environments` config, only the browser environment (`client` on v3, `web` on v2) is applied to the preview; other environments are ignored.

## With Module Federation

Review the [Module Federation example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react-mf) for a full walkthrough.

### Installation

If your Modern.js app uses Module Federation, install `@module-federation/storybook-addon`.


```sh [npm]
npm install @module-federation/storybook-addon -D
```

```sh [yarn]
yarn add @module-federation/storybook-addon -D
```

```sh [pnpm]
pnpm add @module-federation/storybook-addon -D
```

```sh [bun]
bun add @module-federation/storybook-addon -D
```

```sh [deno]
deno add npm:@module-federation/storybook-addon -D
```

### Setup `.storybook/main.ts`

Add the addon and pass the `remotes` option manually. Storybook cannot infer it automatically.

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'
// import moduleFederationConfig from '../module-federation.config'
const moduleFederationConfig = { remotes: {} }

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    'storybook-addon-modernjs',
    {
      name: '@module-federation/storybook-addon',
      options: {
        remotes: moduleFederationConfig.remotes,
      },
    },
  ],
  framework: 'storybook-react-rsbuild',
}
export default config
```

### Setup `modern.config.ts`

When using `@module-federation/storybook-addon`, disable `moduleFederationPlugin` in `modern.config.ts` while Storybook runs.

One approach is to check an environment variable set by your Storybook scripts.

```json title="package.json"
{
  "scripts": {
    "storybook": "STORYBOOK=true storybook dev -p 6006"
  }
}
```

```ts title="modern.config.ts"
import { appTools, defineConfig } from '@modern-js/app-tools'
import { moduleFederationPlugin } from '@module-federation/modern-js'

// https://modernjs.dev/en/configure/app/usage
export default defineConfig({
  runtime: {
    router: true,
  },
  plugins: [
    appTools({
      bundler: 'rspack',
    }),
    ...(process.env.STORYBOOK === 'true' ? [] : [moduleFederationPlugin()]),
  ],
})
```

## Limitations

Modern.js has its own plugin system that transforms configuration before handing it to Rsbuild.

Modern.js also processes user configuration internally, performing complex changes before Rsbuild sees the result.

:::tip
Therefore, the addon has some limitations in Modern.js.
:::

### 🎗 Supported Usages

- Modern.js Configuration files
- Modern.js plugins to modify the configuration
- Rsbuild plugins

### 😪 Unsupported Usages

- Webpack cannot be used, only Rspack is supported.
- SSR configuration will not work in Storybook
- Runtime capabilities, such as `<Link>` navigation
- [Modern.js plugins](https://modernjs.dev/plugin/cli-plugins/api.html) will only call the `config` and `resolveConfig` hooks

### ☎️ Contact Us

We now support Storybook through a Storybook addon, not a Storybook framework. As a result, some features of Modern.js are unavailable in Storybook.

If you have any questions or suggestions with Modern.js & Storybook, feel free to contact us.

- [GitHub](https://github.com/web-infra-dev/modern.js)
- [Modern.js Discord](https://discord.gg/qPCqYg38De)



---
url: /guide/integrations/rslib.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rslib

This addon loads the reusable parts of the Rsbuild config from your Rslib configuration file while keeping library-only settings out of the Storybook preview build.

It also lets you develop the `mf` [(Module Federation)](https://rslib.rs/guide/basic/output-format#mf) format inside Storybook.

See the [React component library example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rslib-react-component) for a full reference implementation.

## Getting started

### Installation


```sh [npm]
npm install @rsbuild/core storybook-addon-rslib -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-addon-rslib -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-addon-rslib -D
```

```sh [bun]
bun add @rsbuild/core storybook-addon-rslib -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-addon-rslib -D
```

Install `@rsbuild/core` directly so the version that the addon and your framework package use is pinned in your own lockfile. Use this alongside the framework package from your project's [framework guide](/guide/framework.md) (e.g. `storybook-react-rsbuild`).

### Setup `.storybook/main.ts`

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['storybook-addon-rslib'],
}

export default config
```

Before the selected Rslib config is merged into Storybook, it passes through the same inherited-config boundary documented in [Builder Options](/guide/configuration.md#builder-options). Plugins remain inherited; use the Storybook CLI's `process.env.STORYBOOK` flag to conditionally omit an app-only side-effect plugin. Use `modifyLibRsbuildConfig` to restore a stripped field explicitly for Storybook, or use Storybook's `rsbuildFinal` for final configuration. Both hooks run after inherited fields are stripped.

Or configure the addon manually:

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    {
      name: 'storybook-addon-rslib',
      options: {
        // Check options section.
      },
    },
  ],
}

export default config
```

## Module Federation

Review the [Rslib Module Federation documentation](https://rslib.rs/guide/advanced/module-federation) to prepare the `mf` output before loading it in Storybook.

## Options

```ts
export interface AddonOptions {
  rslib?: {
    /**
     * `cwd` passed to loadConfig of Rslib
     * @default undefined
     */
    cwd?: string
    /**
     *  `path` passed to loadConfig of Rslib
     * @default undefined
     */
    configPath?: string
    /**
     * The lib config index in `lib` field to use, will be merged with the other fields in the config.
     * Set to a number to use the lib config at that index.
     * Set to `false` to disable using the lib config.
     * @default 0
     */
    libIndex?: number | false
    /**
     * Modify the Rslib lib config before transforming it to Rsbuild config which will be merged
     * with Storybook. You can modify the configuration in the config parameters in place.
     * @experimental subject to change at any time
     * @default undefined
     */
    modifyLibConfig?: (config: LibConfig) => void
    /**
     * Modify the Rsbuild config transformed from lib config after inherited fields are stripped
     * and before merging with Storybook config. You can modify the configuration in the config
     * parameters in place, including explicitly restoring stripped fields.
     * @experimental subject to change at any time
     * @default undefined
     */
    modifyLibRsbuildConfig?: (config: RsbuildConfig) => void
  }
}
```



---
url: /guide/integrations/rstack.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rstack

This addon loads an app or library definition from your Rstack configuration and reuses its Storybook-safe Rsbuild settings in the preview build.

See the [Rstack React app example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rstack-react) and the [Rstack React component example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rstack-react-component) for complete setups.

## Getting started

### Installation


```sh [npm]
npm install @rsbuild/core rstack storybook-addon-rstack -D
```

```sh [yarn]
yarn add @rsbuild/core rstack storybook-addon-rstack -D
```

```sh [pnpm]
pnpm add @rsbuild/core rstack storybook-addon-rstack -D
```

```sh [bun]
bun add @rsbuild/core rstack storybook-addon-rstack -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:rstack npm:storybook-addon-rstack -D
```

Use this alongside the framework package from your project's [framework guide](/guide/framework.md), such as `storybook-react-rsbuild`.

### Setup `.storybook/main.ts`

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['storybook-addon-rstack'],
}

export default config
```

By default, the addon loads `rstack.config.*`, prefers `define.app()` when both app and lib definitions exist, and otherwise falls back to `define.lib()`. Only the selected definition is executed.

## Options

Configure the addon when the defaults do not match your project:

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    {
      name: 'storybook-addon-rstack',
      options: {
        rstack: {
          configFilePath: './rstack.config.ts',
          stack: { type: 'lib', libIndex: 0 },
        },
      },
    },
  ],
}

export default config
```

- `configFilePath`: Optional `string`. Absolute path, or relative to the current working directory. Names the Rstack config file, which is loaded through Rstack's [`loadRstackConfig()`](https://github.com/rstackjs/rstack-cli/blob/main/packages/rstack/src/config.ts).
- `stack`: Which definition to inherit. Omit it to prefer `define.app()` and fall back to `define.lib()`.
  - `{ type: 'app', environment? }`: inherit `define.app()`. `environment` must name an existing environment; see the [builder's environment option](/guide/configuration.md#option-reference).
  - `{ type: 'lib', libIndex? }`: inherit `define.lib()`. `libIndex` is a `number` or `false` (default `0`); `false` inherits only top-level library config.

Setting `stack` requires that definition to exist; a missing definition is an error.

If the selected library config omits its `lib` array, index `0` is an implicit empty entry. An explicit empty array has no valid entry.

## Inherited configuration boundary

Inherited configuration follows the same [Rsbuild configuration boundary](/guide/configuration.md#inherited-rsbuild-configuration).



---
url: /guide/integrations/rspack.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rspack

Rsbuild is built on Rspack, so any configuration you apply in Rsbuild can work with raw Rspack projects too. This guide shows how to connect Storybook Rsbuild to an existing Rspack setup.

Explore the [Rspack React sandbox](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rspack-react-18) for a complete reference implementation.

## Setup

### 1. Install dependencies

Starting from a React example, install `storybook-react-rsbuild` (see the [React framework guide](/guide/framework/react.md)) and add the Rsbuild packages required for Rspack support.


```sh [npm]
npm install @rsbuild/core @rsbuild/plugin-react -D
```

```sh [yarn]
yarn add @rsbuild/core @rsbuild/plugin-react -D
```

```sh [pnpm]
pnpm add @rsbuild/core @rsbuild/plugin-react -D
```

```sh [bun]
bun add @rsbuild/core @rsbuild/plugin-react -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:@rsbuild/plugin-react -D
```

Ensure the following packages are present:

- `storybook`
- `@rsbuild/core`
- `@rsbuild/plugin-react`
- `storybook-react-rsbuild`

### 2. Create `rsbuild.config.ts`

Storybook Rsbuild reads the project's Rsbuild config in the same way that [`@storybook/builder-webpack5` allows custom webpack configs](https://storybook.js.org/docs/builders/webpack#import-a-custom-webpack-configuration). Configure the basics for your Rspack app here.

```ts title="rsbuild.config.ts"
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'

export default defineConfig({
  plugins: [pluginReact()],
})
```

### 3. Configure `.storybook/main.ts`

Match the setup from the [React framework guide](/guide/framework/react.md#configure-storybookmaints) so Storybook uses the Rsbuild builder.

```ts twoslash title=".storybook/main.ts"
// @noErrors
import { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: [],
  addons: [],
}

export default config
```

At this point `npx storybook dev` should launch using the default `@rsbuild/core` and `@rsbuild/plugin-react` configuration. If your project already has its own `rspack.config`, continue with step 4 — story bundles only see what's defined in `rsbuild.config.ts`, so any custom rules, plugins, or aliases that are not mirrored here will silently be missing from your stories.

### 4. Mirror an existing `rspack.config`

If your project maintains a custom `rspack.config.ts` / `rspack.config.cjs` for the application build, mirror its essential pieces in `rsbuild.config.ts`. Storybook does not read `rspack.config` — it reads `rsbuild.config.ts`, so parity has to be explicit.

When porting an existing Rspack project, walk through your `rspack.config` and mirror each of the following if it has been customized:

- **`resolve.alias`** — set on `rsbuild.config.ts` directly under [`resolve.alias`](https://rsbuild.rs/config/resolve/alias), or merge via `tools.rspack` if you prefer to keep a single source of truth.
- **Custom `module.rules` (loaders)** — merge via [`tools.rspack`](https://rsbuild.rs/config/tools/rspack). Note that Rsbuild's built-in plugins (`pluginReact`, `pluginSass`, etc.) already register the most common loaders; only project-specific rules (e.g. `@svgr/webpack`, `less-loader` with custom options, internal codegen loaders) need to be ported.
- **Custom `plugins`** — merge via `tools.rspack`.
- **Custom `externals`, `output.publicPath`, `experiments`, etc.** — merge via `tools.rspack`.

The example below imports an existing Rspack config and mirrors its `resolve.alias` plus a custom `less-loader` rule:

```ts title="rsbuild.config.ts" {3,8-10,12-15}
import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
// import rspackConfig from './rspack.config.cjs'
const rspackConfig = {
  resolve: { alias: { '@app': './src' } },
  module: { rules: [{}, {}, { loader: 'less-loader' }] },
} as any

export default defineConfig({
  plugins: [pluginReact()],
  resolve: {
    alias: rspackConfig.resolve?.alias,
  },
  tools: {
    rspack: (config) => {
      const lessLoader = rspackConfig.module.rules[2]
      config.module!.rules!.push(lessLoader)
      return config
    },
  },
})
```

Refer to [`tools.rspack`](https://rsbuild.rs/config/tools/rspack) for every customization hook.



---
url: /guide/migration.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Migration

This guide covers migrating an existing Storybook project from the **webpack5** or **Vite** framework to **Storybook Rsbuild** (e.g. `storybook-react-rsbuild`).

:::tip Using an AI coding agent?
Your agent can handle this migration automatically. Install the agent skills and ask it to migrate your project:


```sh [npx]
npx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [bunx]
bunx skills add rstackjs/agent-skills --skill storybook-rsbuild
```

```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill storybook-rsbuild
```

:::

:::info Storybook versions

Match your Storybook version to the correct storybook-rsbuild release:

| Storybook | Storybook Rsbuild |
| --------- | ----------------- |
| v10       | `^3`              |
| v9        | `^2`              |
| v8        | `^1`              |

:::

## From Storybook Webpack5 Framework

If your `.storybook/main.ts` uses a webpack5 framework package (e.g. `@storybook/react-webpack5`, `@storybook/vue3-webpack5`), follow this section.

### 1. Replace packages

Uninstall the old webpack5 framework package, and install the Rsbuild equivalent along with `@rsbuild/core`.

For example, to migrate a React project:


```sh [npm]
npm install @rsbuild/core storybook-react-rsbuild -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-react-rsbuild -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-react-rsbuild -D
```

```sh [bun]
bun add @rsbuild/core storybook-react-rsbuild -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-react-rsbuild -D
```

Then remove the old packages:


```sh [npm]
npm remove @storybook/builder-webpack5 @storybook/react-webpack5
```

```sh [yarn]
yarn remove @storybook/builder-webpack5 @storybook/react-webpack5
```

```sh [pnpm]
pnpm remove @storybook/builder-webpack5 @storybook/react-webpack5
```

```sh [bun]
bun remove @storybook/builder-webpack5 @storybook/react-webpack5
```

```sh [deno]
deno remove npm:@storybook/builder-webpack5 npm:@storybook/react-webpack5
```

The framework package (e.g. `storybook-react-rsbuild`) includes `storybook-builder-rsbuild` as a dependency — you do **not** need to install the builder separately.

#### Package mapping

| Old (webpack5)                       | New (Rsbuild)                      |
| ------------------------------------ | ---------------------------------- |
| `@storybook/react-webpack5`          | `storybook-react-rsbuild`          |
| `@storybook/vue3-webpack5`           | `storybook-vue3-rsbuild`           |
| `@storybook/html-webpack5`           | `storybook-html-rsbuild`           |
| `@storybook/web-components-webpack5` | `storybook-web-components-rsbuild` |

### 2. Update `.storybook/main.ts`

```ts twoslash title=".storybook/main.ts"
// @noErrors
// Before
// import type { StorybookConfig } from '@storybook/react-webpack5'
// After
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  // Before: framework: '@storybook/react-webpack5',
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
}

export default config
```

### 3. Convert `webpackFinal` to `rsbuildFinal`

:::warning Use `mergeRsbuildConfig` for modifications
Always use [`mergeRsbuildConfig`](https://rsbuild.rs/api/javascript-api/core#mergersbuildconfig) from `@rsbuild/core` to modify the config. Directly mutating properties like `config.tools.rspack = {...}` may not work because internal configs can be arrays of functions/objects, and direct assignment may be silently ignored.
:::

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: [],
  // Before:
  // webpackFinal: async (config) => {
  //   config.resolve.alias['@components'] = path.resolve(__dirname, '../src/components')
  //   config.module.rules.push({ test: /\.svg$/, use: ['@svgr/webpack'] })
  //   return config
  // },

  // After:
  rsbuildFinal: async (config) => {
    return mergeRsbuildConfig(config, {
      resolve: {
        alias: {
          '@components': './src/components',
        },
      },
      // For SVG, use @rsbuild/plugin-svgr
    })
  },
}

export default config
```

:::tip Use relative paths in `resolve.alias`
Rsbuild resolves alias values relative to the project root. Use `'./src/components'`, not `path.resolve(__dirname, '../src/components')`. The relative form is shorter and avoids `__dirname` issues in ESM configs.
:::

### 4. Handle webpack-dependent addons

Some Storybook addons use `webpackFinal` internally. Move them from `addons` to `webpackAddons`:

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: [],
  // Regular addons (framework-agnostic)
  addons: ['@storybook/addon-docs', '@storybook/addon-onboarding'],
  // Addons that depend on webpack loaders/plugins
  webpackAddons: ['@storybook/addon-coverage'],
}

export default config
```

The `webpackAddons` field runs each addon's `webpackFinal` hook and translates the resulting webpack config into Rspack config automatically.

:::tip Common addons that need `webpackAddons`
A few addons hook `webpackFinal` internally and must move to `webpackAddons` (or be replaced with the Rsbuild-native equivalent):

- `@storybook/addon-styling-webpack` — global CSS / PostCSS / Sass / Less. Either route via `webpackAddons` or replace with [`@rsbuild/plugin-postcss`](https://rsbuild.rs/plugins/list/plugin-postcss), [`@rsbuild/plugin-sass`](https://rsbuild.rs/plugins/list/plugin-sass), or [`@rsbuild/plugin-less`](https://rsbuild.rs/plugins/list/plugin-less).
- `@storybook/addon-coverage` — collects test coverage; route via `webpackAddons`.
- `@storybook/preset-create-react-app` — CRA compatibility; route via `webpackAddons`.

If an addon's name ends in `-webpack` or its docs mention `webpackFinal`, assume it needs this treatment. Silently dropping a webpack-only addon is a regression even if `storybook build` still passes.
:::

### 5. Convert common webpack patterns

| webpack pattern                    | Rsbuild equivalent                                                    |
| ---------------------------------- | --------------------------------------------------------------------- |
| `config.resolve.alias`             | `resolve.alias` in `rsbuildFinal`                                     |
| `config.resolve.extensions`        | `resolve.extensions` (Rsbuild has sensible defaults)                  |
| `config.module.rules` (loaders)    | `tools.rspack` or Rsbuild plugins                                     |
| `config.plugins` (webpack plugins) | `tools.rspack` for Rspack plugins                                     |
| `DefinePlugin`                     | `source.define`                                                       |
| `css-loader` / `style-loader`      | Built-in, use `tools.cssLoader` if customizing                        |
| `sass-loader`                      | [`@rsbuild/plugin-sass`](https://rsbuild.rs/plugins/list/plugin-sass) |
| `less-loader`                      | [`@rsbuild/plugin-less`](https://rsbuild.rs/plugins/list/plugin-less) |
| `file-loader` / `url-loader`       | Built-in asset modules                                                |
| SVGR                               | [`@rsbuild/plugin-svgr`](https://rsbuild.rs/plugins/list/plugin-svgr) |

:::tip Rspack plugin compatibility
Not all webpack plugins are compatible with Rspack. Check the [Rspack compatibility guide](https://rspack.rs/guide/compatibility/plugin) for details.
:::

***

## From Storybook Vite Framework

If your `.storybook/main.ts` uses a Vite framework package (e.g. `@storybook/react-vite`, `@storybook/vue3-vite`), follow this section.

### 1. Replace packages

Uninstall the old Vite framework package, and install the Rsbuild equivalent along with `@rsbuild/core`.

For example, to migrate a React project:


```sh [npm]
npm install @rsbuild/core storybook-react-rsbuild -D
```

```sh [yarn]
yarn add @rsbuild/core storybook-react-rsbuild -D
```

```sh [pnpm]
pnpm add @rsbuild/core storybook-react-rsbuild -D
```

```sh [bun]
bun add @rsbuild/core storybook-react-rsbuild -D
```

```sh [deno]
deno add npm:@rsbuild/core npm:storybook-react-rsbuild -D
```

Then remove the old packages:


```sh [npm]
npm remove @storybook/builder-vite @storybook/react-vite
```

```sh [yarn]
yarn remove @storybook/builder-vite @storybook/react-vite
```

```sh [pnpm]
pnpm remove @storybook/builder-vite @storybook/react-vite
```

```sh [bun]
bun remove @storybook/builder-vite @storybook/react-vite
```

```sh [deno]
deno remove npm:@storybook/builder-vite npm:@storybook/react-vite
```

#### Package mapping

| Old (Vite)                       | New (Rsbuild)                      |
| -------------------------------- | ---------------------------------- |
| `@storybook/react-vite`          | `storybook-react-rsbuild`          |
| `@storybook/vue3-vite`           | `storybook-vue3-rsbuild`           |
| `@storybook/html-vite`           | `storybook-html-rsbuild`           |
| `@storybook/web-components-vite` | `storybook-web-components-rsbuild` |

### 2. Update `.storybook/main.ts`

```ts twoslash title=".storybook/main.ts"
// @noErrors
// Before
// import type { StorybookConfig } from '@storybook/react-vite'
// After
import type { StorybookConfig } from 'storybook-react-rsbuild'

const config: StorybookConfig = {
  // Before: framework: '@storybook/react-vite',
  framework: 'storybook-react-rsbuild',
  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
}

export default config
```

### 3. Convert `viteFinal` to `rsbuildFinal`

```ts twoslash title=".storybook/main.ts"
// @noErrors
import type { StorybookConfig } from 'storybook-react-rsbuild'
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
  stories: [],
  // Before:
  // viteFinal: async (config) => {
  //   config.resolve.alias['@'] = path.resolve(__dirname, '../src')
  //   return config
  // },

  // After:
  rsbuildFinal: async (config) => {
    return mergeRsbuildConfig(config, {
      resolve: {
        alias: {
          '@': './src',
        },
      },
    })
  },
}

export default config
```

:::tip Use relative paths in `resolve.alias`
Rsbuild resolves alias values relative to the project root. Use `'./src'`, not `path.resolve(__dirname, '../src')`. The relative form is shorter and avoids `__dirname` issues in ESM configs.
:::

### 4. Convert common Vite patterns

| Vite pattern              | Rsbuild equivalent                               |
| ------------------------- | ------------------------------------------------ |
| `resolve.alias`           | `resolve.alias` in `rsbuildFinal`                |
| `plugins: [react()]`      | Auto-configured by framework package             |
| `css.preprocessorOptions` | `@rsbuild/plugin-sass` or `@rsbuild/plugin-less` |
| `define`                  | `source.define`                                  |
| `server.proxy`            | `server.proxy`                                   |
| `build.target`            | `output.target`                                  |

:::tip Vite plugins are not compatible
Vite plugins cannot be used with Rsbuild. Find equivalent Rsbuild plugins at the [Rsbuild plugin list](https://rsbuild.rs/plugins/list/).
:::

***

## Verification

After migration, verify:

1. `npx storybook dev` starts without errors
2. All stories render correctly
3. HMR works (edit a component, see it update)
4. `npx storybook build` completes successfully
5. Addons function correctly (especially docs, controls, actions)

## Debugging

Enable Rsbuild debug mode to inspect the generated config:

```bash
DEBUG=rsbuild storybook dev
```

Check the CLI output to see where the Rsbuild and Rspack configs are written.



---
url: /guide/troubleshooting.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Troubleshooting

## Deploy Storybook to a subdirectory or subpath

> Since v3.3.3. In v3.3.2 and earlier, the default `assetPrefix` was `'/'` (absolute), which required manual configuration for subdirectory deployment.

The Rsbuild builder uses relative asset paths by default — the same as the official Vite (`base: './'`) and webpack (`publicPath: ''`) builders. Storybook can be deployed to any subdirectory (e.g., `https://example.com/storybook/`) without extra configuration.

## Serving static assets from a CDN

> Since v3.3.3. In v3.3.2 and earlier, this was not supported.

To serve Storybook's JS/CSS bundles from a separate CDN origin (e.g., `https://cdn.example.com/assets/`), set [`output.assetPrefix`](https://rsbuild.rs/config/output/asset-prefix) to the CDN URL:

```js
import { mergeRsbuildConfig } from '@rsbuild/core'

const config: StorybookConfig = {
  // --snip--
  rsbuildFinal: (config) => {
    return mergeRsbuildConfig(config, {
      output: {
        assetPrefix: 'https://cdn.example.com/',
      },
    })
  },
  // --snip--
}
```

The preview template correctly handles absolute URLs, so JS/CSS bundles will be loaded from the CDN while `iframe.html` can remain on the origin server. Note that the CDN must serve appropriate [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) since the bundles are loaded via ES module imports.

> \[!NOTE]
> This is an improvement over the [official webpack5 builder](https://github.com/storybookjs/storybook/issues/23481), which does not support CDN asset hosting due to its template always prepending `./` to import paths.

## `Template.toString()` shows compiled code in Docs source snippet

When using the CSF 2 `Template.bind({})` pattern and `Template.toString()` to display source code in the Docs addon, the snippet shows bundler-compiled output instead of your original source.

This is expected — `Function.prototype.toString()` serializes the **runtime** function, which has already been transformed by the bundler. This is not specific to the Rsbuild builder; the same happens with webpack and Vite.

Storybook recommends using the [CSF 3 format](https://storybook.js.org/docs/api/csf) with the automatic source snippet feature, or manually providing source code through [docs source parameters](https://storybook.js.org/docs/api/doc-blocks/doc-block-source). See the [Storybook Docs documentation](https://storybook.js.org/docs/writing-docs/autodocs) for more details.

## Build errors from unexpected files

> \[!NOTE]
> This issue mostly affects older Rspack versions. Modern Rspack handles `webpackInclude` correctly.

If you encounter issues where Rspack bundles files it shouldn't (like Markdown files in unexpected places), you can use `rspack.IgnorePlugin` to exclude them.

```js
// .storybook/main.js
import path from 'path'
import { mergeRsbuildConfig } from '@rsbuild/core'

export default {
  framework: 'storybook-react-rsbuild',
  async rsbuildFinal(config) {
    return mergeRsbuildConfig(config, {
      tools: {
        rspack: (config, { addRules, appendPlugins, rspack, mergeConfig }) => {
          return mergeConfig(config, {
            plugins: [
              new rspack.IgnorePlugin({
                checkResource: (resource, context) => {
                  const absPathHasExt = path.extname(resource)
                  if (absPathHasExt === '.md') {
                    return true
                  }

                  return false
                },
              }),
            ],
          })
        },
      },
    })
  },
}
```

## MSW integration and lazy compilation

When `mockServiceWorker.js` is found in one of the `staticDirs` entries — the convention used by [`msw-storybook-addon`](https://github.com/mswjs/msw-storybook-addon) and any hand-rolled MSW setup — the builder automatically disables lazy compilation and logs a warning at startup.

This is necessary because MSW's Service Worker intercepts every `fetch` from the preview iframe, including the dev-server's lazy-compilation RPC (`POST /lazy-compilation-using-`). The SW's passthrough re-issues a fresh `fetch(clonedRequest)` that the dev-server aborts, which can leave stories stuck on a blank iframe during cold loads. The issue is rooted in how the lazy-compilation runtime talks to the dev-server via a stateful RPC channel — not a defect of the builder itself — and also affects the official `@storybook/builder-webpack5` when lazy compilation is manually enabled. A related failure mode is discussed upstream in [mswjs/msw#834](https://github.com/mswjs/msw/issues/834) (SW intercepting dev-server HMR SSE).

Leaving the auto-disable in place is the safest choice. If you never explicitly set `lazyCompilation`, no action is required on your side.

If your project needs lazy compilation alongside MSW, set `lazyCompilation` explicitly in your builder options — an explicit value always takes priority over the MSW auto-disable:

```ts
// .storybook/main.ts
export default {
  framework: {
    options: {
      builder: {
        // Opt back in — expect occasional blank iframes on cold loads.
        lazyCompilation: { entries: false },
      },
    },
  },
}
```

When you opt back in, patch `public/mockServiceWorker.js` to let lazy-compilation RPC bypass MSW. Add this guard at the top of the `fetch` event listener, before MSW's own logic runs:

```js
// public/mockServiceWorker.js
self.addEventListener('fetch', function (event) {
  // Let Rspack / webpack's lazy-compilation RPC bypass MSW so the
  // dev-server sees the original client request, not a re-issued clone.
  if (event.request.url.includes('/lazy-compilation-using-')) {
    return
  }
  // ...existing MSW handler logic
})
```

Caveats:

- `msw init` regenerates `mockServiceWorker.js` and will overwrite the patch. Re-apply it after upgrading MSW, or automate via a postinstall script that appends the guard if it is missing.
- The bypass is scoped strictly to the lazy-compilation path; normal story requests still go through MSW and your handlers behave as before.
- The substring match covers both the Rspack implementation (same-origin `POST /lazy-compilation-using-`) and webpack5's (dedicated random-port `GET /lazy-compilation-using-<module-path>`), so the same guard also works if you ever move to the official webpack5 builder with lazy compilation enabled.

## Why do sandboxes use `getAbsolutePath` to resolve the framework?

See [Storybook's FAQ](https://storybook.js.org/docs/faq#how-do-i-fix-module-resolution-in-special-environments) for the explanation.

## How can I inspect the Rsbuild or Rspack config used by Storybook?

Rsbuild offers a [CLI debug mode](https://rsbuild.rs/guide/debug/debug-mode). Enable it when running Storybook to dump the generated configuration paths.

In development:

```bash
DEBUG=rsbuild storybook dev
```

In production:

```bash
DEBUG=rsbuild storybook build
```

Check the CLI output to see where the Rsbuild and Rspack configs are written.

## Can I use this builder with Rspack directly?

Yes. Rsbuild is built on Rspack, so you can feed your Rspack configuration into the Rsbuild builder. Follow the [Rspack integration guide](/guide/integrations/rspack.md) to learn how.



---
url: /index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Storybook Rsbuild

The Rsbuild integration for Storybook

> The fast, consistent Storybook experience backed by Rsbuild.

[Quick Start](/guide/) | [GitHub](https://github.com/rstackjs/storybook-rsbuild)

## Features

- 🧬 **Coherent configuration**: Share one Rsbuild setup between your app and Storybook, and extend it only when you need to.
- 🌈 **Multi-framework support**: Work with React, Vue, Lit, and other popular web frameworks out of the box.
- 🦀 **Works with Rspack and webpack 5**: Use Rsbuild directly or plug into existing webpack 5 and Rspack projects.
- 🧩 **Compatible with webpack addons**: Keep using your favorite webpack 5 Storybook addons without extra configuration.
- 🚀 **Lightning fast build speeds**: Experience significantly faster build times with Rspack's optimized bundling engine.
- 💎 **Modern development experience**: Built-in TypeScript support, CSS modules, and asset handling for a smooth developer workflow.