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

# Rstack

该 addon 会从 Rstack 配置中加载 app 或 library 定义，并在 preview build 中复用适合 Storybook 的 Rsbuild 设置。

完整配置请参考 [Rstack React 应用示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rstack-react) 和 [Rstack React 组件库示例](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/rstack-react-component)。

## 快速开始

### 安装


```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
```

请将它与你在项目 [framework 指南](/zh/guide/framework.md) 中所选的 framework 包配合使用，例如 `storybook-react-rsbuild`。

### 配置 `.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
```

addon 默认在 Storybook 启动的目录尝试加载 Rstack 的配置文件 `rstack.config.*`。如果 app 和 lib 定义同时存在，它会优先选择 `define.app()`，否则回退到 `define.lib()`。

更改配置文件路径或手动指定选中的 Storybook 运行的目标，可以通过 `options.rstack` 配置。

## 选项

默认行为不适合项目时，可以手动配置 addon：

```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`：可选的 `string`。绝对路径，或相对于当前工作目录的路径，用来指定目标的 Rstack config file，被指定的文件将通过 Rstack 的 [`loadRstackConfig()`](https://github.com/rstackjs/rstack-cli/blob/main/packages/rstack/src/config.ts) 加载。
- `stack`：指定要继承的定义。不设置时优先选择 `define.app()`，再回退到 `define.lib()`。
  - `{ type: 'app', environment? }`：继承 `define.app()`。`environment` 必须指定已有的 environment 名称；参见 [builder 的 environment 选项](/zh/guide/configuration.md#选项参考)。
  - `{ type: 'lib', libIndex? }`：继承 `define.lib()`。`libIndex` 为 `number` 或 `false`，默认为 `0`；使用 `false` 时只继承顶层 library 配置。

设置 `stack` 时对应的定义必须存在，否则报错。

选中的 library 配置省略 `lib` 数组时，index `0` 对应一个隐式空 entry。显式空数组则没有有效 entry。

## 继承配置边界

继承配置遵循相同的 [Rsbuild 配置边界](/zh/guide/configuration.md#继承的-rsbuild-配置)。