{"id":15240,"library":"storybook-react-rsbuild","title":"Storybook React Rsbuild Framework","description":"storybook-react-rsbuild is a Storybook framework integration designed for React projects that leverage Rsbuild as their underlying build tool. It provides a fast and efficient development experience for React components in isolation, utilizing Rsbuild and Rspack for superior build performance and Hot Module Replacement (HMR) compared to traditional Webpack-based Storybook setups. The current stable version is `3.3.3`, with active development indicated by frequent patch and minor releases addressing bugs and introducing new features. This package acts as the bridge, allowing Storybook to seamlessly integrate with your existing Rsbuild configuration. It is crucial for projects aiming for optimized build times within the Storybook environment while working with React.","status":"active","version":"3.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/rstackjs/storybook-rsbuild","tags":["javascript","storybook","rsbuild","rspack","react"],"install":[{"cmd":"npm install storybook-react-rsbuild","lang":"bash","label":"npm"},{"cmd":"yarn add storybook-react-rsbuild","lang":"bash","label":"yarn"},{"cmd":"pnpm add storybook-react-rsbuild","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Essential for the Rsbuild build system integration with Storybook. The package depends on specific versions for compatibility.","package":"@rsbuild/core","optional":false},{"reason":"Core React library, required for developing React components and Storybook's React renderer.","package":"react","optional":false},{"reason":"React's DOM-specific rendering library, crucial for mounting React components in the browser.","package":"react-dom","optional":false},{"reason":"The core Storybook package, providing the main UI and component development environment.","package":"storybook","optional":false},{"reason":"Required for type-checking and proper integration in TypeScript projects, especially for configuration files.","package":"typescript","optional":true}],"imports":[{"note":"Used for type-checking your `.storybook/main.ts` configuration file, ensuring adherence to the Storybook configuration schema specific to the Rsbuild framework.","wrong":"import { StorybookConfig } from 'storybook-react-rsbuild'; // Incorrect for type-only import","symbol":"StorybookConfig","correct":"import type { StorybookConfig } from 'storybook-react-rsbuild';"},{"note":"This string literal is used within your `.storybook/main.js` or `.storybook/main.ts` file to specify that Storybook should use the `storybook-react-rsbuild` framework and builder.","wrong":"framework: '@storybook/react-webpack5', // Uses the wrong Storybook builder","symbol":"framework.name","correct":"framework: { name: '@storybook/react-rsbuild', options: {} }"},{"note":"While not directly from `storybook-react-rsbuild`, `mergeRsbuildConfig` from `@rsbuild/core` is crucial for customizing the underlying Rsbuild configuration within the `rsbuildFinal` function in `main.ts` to prevent direct mutation issues.","wrong":"import { mergeRsbuildConfig } from 'storybook-react-rsbuild'; // Not exported by this package","symbol":"mergeRsbuildConfig","correct":"import { mergeRsbuildConfig } from '@rsbuild/core';"}],"quickstart":{"code":"import type { StorybookConfig } from 'storybook-react-rsbuild';\nimport { mergeRsbuildConfig } from '@rsbuild/core';\n\n// .storybook/main.ts\nconst config: StorybookConfig = {\n  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],\n  addons: [\n    '@storybook/addon-links',\n    '@storybook/addon-essentials',\n    '@storybook/addon-onboarding',\n    '@storybook/addon-interactions',\n  ],\n  framework: {\n    name: '@storybook/react-rsbuild',\n    options: {},\n  },\n  docs: {\n    autodocs: 'tag',\n  },\n  // Example of customizing Rsbuild config\n  rsbuildFinal: async (currentConfig, { configType }) => {\n    if (configType === 'PRODUCTION') {\n      return mergeRsbuildConfig(currentConfig, {\n        performance: { removeConsole: true },\n      });\n    }\n    return currentConfig;\n  },\n};\nexport default config;\n\n// src/components/Button.tsx\nimport React from 'react';\n\ninterface ButtonProps {\n  label: string;\n  primary?: boolean;\n  onClick?: () => void;\n}\n\nexport const Button: React.FC<ButtonProps> = ({ label, primary = false, onClick }) => {\n  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';\n  return (\n    <button type=\"button\" className={['storybook-button', mode].join(' ')} onClick={onClick}>\n      {label}\n    </button>\n  );\n};\n\n// src/components/Button.stories.tsx\nimport type { Meta, StoryObj } from '@storybook/react';\nimport { Button } from './Button';\n\nconst meta: Meta<typeof Button> = {\n  component: Button,\n  title: 'Example/Button',\n  tags: ['autodocs'],\n  argTypes: {\n    backgroundColor: { control: 'color' },\n  },\n};\n\nexport default meta;\ntype Story = StoryObj<typeof Button>;\n\nexport const Primary: Story = {\n  args: {\n    primary: true,\n    label: 'Button',\n  },\n};\n\nexport const Secondary: Story = {\n  args: {\n    label: 'Button',\n  },\n};\n","lang":"typescript","description":"This quickstart demonstrates how to configure Storybook to use `storybook-react-rsbuild` as its framework, define a simple React component, and create its corresponding Storybook stories in TypeScript. It also includes an example of customizing the underlying Rsbuild configuration."},"warnings":[{"fix":"Upgrade your Storybook core packages to v10+ first, then install `storybook-react-rsbuild` version 3.x.x. Consult Storybook's migration guides for a smooth transition.","message":"Version `3.0.0` of `storybook-react-rsbuild` introduced breaking changes to align with Storybook v10. Projects on older Storybook versions (v9 or earlier) must follow Storybook's official migration guide to v10 before upgrading this package.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Storybook core packages (`storybook`, `@storybook/react`, etc.) are updated to at least version `10.1.0`.","message":"Starting from `v3.1.0`, `storybook-react-rsbuild` explicitly requires Storybook peer dependency version `10.1.0` or higher. Using older Storybook versions will lead to compatibility issues.","severity":"breaking","affected_versions":">=3.1.0"},{"fix":"For absolute paths, configure `output.assetPrefix: '/'` in your `rsbuildFinal` function within `.storybook/main.ts`. Note that this might break subdirectory deployments. Choose the option that fits your deployment scenario.","message":"When hosting Storybook in a subdirectory or using a CDN, CSS `url()` references to static assets might resolve incorrectly in production builds. This is a known trade-off of relative paths. Since `v3.3.3`, the default is relative paths for subdirectory support, which can cause this issue if not handled.","severity":"gotcha","affected_versions":">=3.3.3"},{"fix":"Always use `mergeRsbuildConfig` from `@rsbuild/core` to safely modify the Rsbuild configuration object, ensuring changes are applied correctly.","message":"Directly mutating properties of the Rsbuild configuration object within `rsbuildFinal` (e.g., `config.tools.rspack = {...}`) may lead to unexpected behavior or be silently ignored due to internal configurations being arrays of functions/objects.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Review the Node.js compatibility requirements for your Storybook and `storybook-react-rsbuild` versions. Consider downgrading Node.js or checking for official workarounds/updates from Storybook or Rsbuild.","cause":"This error can occur with specific Node.js versions (e.g., Node.js 22.18.0) due to changes in Node.js's ESM loader, affecting how Storybook builders resolve modules.","error":"TypeError: Cannot read properties of undefined (reading 'getStatus') at ModuleLoader.getModuleJobForRequire"},{"fix":"Ensure the package is installed as a dev dependency: `npm install --save-dev storybook-react-rsbuild` or `yarn add --dev storybook-react-rsbuild`. Verify the package name in `.storybook/main.js` or `.storybook/main.ts` is `\"@storybook/react-rsbuild\"` (with the '@' scope).","cause":"The `storybook-react-rsbuild` package is not installed or incorrectly referenced in your project's `node_modules`.","error":"Module not found: Error: Can't resolve '@storybook/react-rsbuild' in '.../.storybook'"},{"fix":"Upgrade all Storybook-related packages in your project to v10 or later. Run `npx storybook@latest upgrade` and then ensure `storybook-react-rsbuild` is also updated to its latest compatible version.","cause":"This error indicates a version mismatch between `storybook-react-rsbuild` (which is for Storybook v10+) and an older Storybook core installation.","error":"Error: Storybook's React preset is not compatible with Storybook v9. Please upgrade to Storybook v10."}],"ecosystem":"npm"}