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.

Storybook Documentation

This guide focuses on Rsbuild-specific configurations. For general Storybook configuration (stories, addons, refs, etc.), please refer to the Storybook 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 in the Webpack builder.

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

Use

mergeRsbuildConfig for modifications Always use 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.

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild';
import { import mergeRsbuildConfigmergeRsbuildConfig } from '@rsbuild/core';

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: string[]stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: never[]addons: [],
  async function rsbuildFinal(config: any, { configType }: {
    configType: any;
}): Promise<any>
rsbuildFinal(config: anyconfig, { configType: anyconfigType }) {
    // Customize Rsbuild config here
    if (configType: anyconfigType === 'PRODUCTION') {
      return import mergeRsbuildConfigmergeRsbuildConfig(config: anyconfig, {
        performance: {
    removeConsole: boolean;
}
performance: {
          removeConsole: booleanremoveConsole: true,
        },
      });
    }

    // Example: add resolve alias
    return import mergeRsbuildConfigmergeRsbuildConfig(config: anyconfig, {
      resolve: {
    alias: {
        '@components': string;
    };
}
resolve: {
        alias: {
    '@components': string;
}
alias: {
          '@components': './src/components',
        },
      },
    });
  },
};

export default const config: StorybookConfigconfig;

Builder Options

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

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild';

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: never[]stories: [],
  core: {
    builder: {
        name: string;
        options: {
            rsbuildConfigPath: string;
            fsCache: boolean;
        };
    };
}
core: {
    builder: {
    name: string;
    options: {
        rsbuildConfigPath: string;
        fsCache: boolean;
    };
}
builder: {
      name: stringname: 'storybook-builder-rsbuild',
      options: {
    rsbuildConfigPath: string;
    fsCache: boolean;
}
options: {
        // Path to your existing rsbuild.config.ts
        // Defaults to the root rsbuild.config.ts if found
        rsbuildConfigPath: stringrsbuildConfigPath: './custom-rsbuild.config.ts',
        
        // Enable filesystem cache for faster rebuilds
        // Default: false
        fsCache: booleanfsCache: true,
        
        // Lazy-compile entries as well as dynamic imports
        // lazyCompilation: true,

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

export default const config: StorybookConfigconfig;

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 and storybook-addon-modernjs. Function-form tools.rspack values are opaque and cannot be stripped. Prefer a dedicated Rsbuild environment 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`	`{ entries: false }` (development); `false` (production)	Configures Rspack's lazy compilation.
`environment`	`string`	`undefined`	Selects a specific environment from Rsbuild config.

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.

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild';

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: never[]stories: [],
  // Addons that depend on Webpack loaders/plugins
  webpackAddons: string[]webpackAddons: [
    '@storybook/addon-coverage',
  ],
};

export default const config: StorybookConfigconfig;

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.

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild';

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: {
    name: string;
    options: {
        strictMode: boolean;
        legacyRootApi: boolean;
    };
}
framework: {
    name: stringname: 'storybook-react-rsbuild',
    options: {
    strictMode: boolean;
    legacyRootApi: boolean;
}
options: {
      // Configure strict mode
      strictMode: booleanstrictMode: true,
      
      // Use legacy ReactDOM.render instead of createRoot (React 18+)
      legacyRootApi: booleanlegacyRootApi: false,
    },
  },
  stories: never[]stories: [],
  typescript: {
    reactDocgen: string;
    reactDocgenTypescriptOptions: {
        propFilter: (prop: any) => boolean;
    };
}
typescript: {
    // Configure docgen for TypeScript
    // 'react-docgen-typescript' | 'react-docgen' | false
    reactDocgen: stringreactDocgen: 'react-docgen-typescript',
    
    // Pass options to react-docgen-typescript-plugin
    reactDocgenTypescriptOptions: {
    propFilter: (prop: any) => boolean;
}
reactDocgenTypescriptOptions: {
      propFilter: (prop: any) => booleanpropFilter: (prop: anyprop) => {
        return prop: anyprop.parent ? !/node_modules/.RegExp.test(string: string): booleanReturns a Boolean value that indicates whether or not a pattern exists in a searched string.
@paramstring  String on which to perform the search.test(prop: anyprop.parent.fileName) : true;
      },
    },
  }
};

export default const config: StorybookConfigconfig;

TypeScript Options

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

.storybook/main.ts

import type { import StorybookConfigStorybookConfig } from 'storybook-react-rsbuild';

const const config: StorybookConfigconfig: import StorybookConfigStorybookConfig = {
  framework: stringframework: 'storybook-react-rsbuild',
  stories: never[]stories: [],
  typescript: {
    check: boolean;
    checkOptions: {
        typescript: {
            memoryLimit: number;
        };
    };
}
typescript: {
    // Enable/disable fork-ts-checker-webpack-plugin
    check: booleancheck: true,
    
    // Options passed to fork-ts-checker-webpack-plugin
    checkOptions: {
    typescript: {
        memoryLimit: number;
    };
}
checkOptions: {
      typescript: {
    memoryLimit: number;
}
typescript: {
        memoryLimit: numbermemoryLimit: 4096,
      },
    },
  },
};

export default const config: StorybookConfigconfig;

See Storybook TypeScript Docs 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:

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

#Configuration

#rsbuildFinal

#Builder Options

#Inherited Rsbuild Configuration

#Option Reference

#Webpack Addons Compatibility

#Framework Options

#React Options

#TypeScript Options

#Preview Output Layout

Configuration

rsbuildFinal

Builder Options

Inherited Rsbuild Configuration

Option Reference

Webpack Addons Compatibility

Framework Options

React Options

TypeScript Options

Preview Output Layout