---
sidebar_position: 15
---

# 使用 Storybook

[Storybook](https://storybook.js.org/) 是一个专门用于组件调试的工具，它围绕着组件开发提供了：

- 丰富多样的调试能力
- 可与一些测试工具结合使用
- 可重复使用的文档内容
- 可分享能力
- 工作流程自动化

:::tip
本教程适用于新版 Storybook V7 用户，如果你在使用老版本 Storybook V6 (有使用 @modern-js/plugin-storybook 插件)，可参考 [迁移指南](#迁移指南) 进行升级。
:::

## 快速开始

Modern.js 默认集成了 Storybook 的调试能力，当我们想要对组件进行调试的时候，可以通过以下方式启用 Storybook 调试功能：

```bash
$ npx modern new
? 请选择你想要的操作 启用可选功能
? 请选择功能名称 启用「Storybook」V7
```

该命令会创建好 Storybook 常用的模版，包括：

- 创建配置文件夹 `.storybook`，以及默认配置文件 `.storybook/main.ts`
- 创建 stories 组件示例
- 更新 package.json，新增依赖 @storybook/addon-essential 和 @modern-js/storybook，以及创建 storybook 相关脚本

运行 `npm run storybook` 即可启动 Storybook 预览。

## 开启 Rspack 构建

Rspack 构建速度非常快，在 Modern.js 中只需要如下配置即可使用 Rspack 作为构建工具。

```diff filename='.storybook/main.js'
const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
-      bundler: 'webpack'
+      bundler: 'rspack'
    },
  },
  typescript: {
-    reactDocgen: 'react-docgen-typescript'
+    reactDocgen: 'react-docgen'
  }
};

export default config;
```

注意上面配置中，更改了 reactDocgen 配置，因为 Rspack 目前还不支持 @storybook/react-docgen-typescript-plugin。

## 配置

在 `.storybook/main.js` 中包含一些配置。

### configPath

- **类型**: `string`
- **默认值**: `modern.config.(j|t)s`

用于指定配置文件路径。

例如

```javascript filename='.storybook/main.js'
const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
      configPath: 'modern.storybook.config.ts',
    },
  },
};

export default config;
```

### bundler

- **类型**: `'webpack' | 'rspack'`
- **默认值**: `webpack`

指定底层构建工具使用 Webpack 还是 Rspack。

例如

```javascript filename='.storybook/main.js'
const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
      bundler: 'rspack',
    },
  },
};

export default config;
```

### builderConfig

- **类型**: `BuilderConfig`
- **默认值**: `undefined`

更改构建配置，该配置比配置文件拥有更高的优先级，若不想使用配置文件，也可直接在此处指定。

例如

```javascript filename='.storybook/main.js'
const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
      builderConfig: {
        alias: {
          react: require.resolve('react'),
          'react-dom': require.resolve('react-dom'),
        },
      },
    },
  },
};

export default config;
```

## 命令行

@modern-js/storybook 代理了部分 storybook cli 的命令。

### storybook dev

启动 Storybook，详情请看 [storybook#dev](https://storybook.js.org/docs/react/api/cli-options#dev)

### storybook build

对 Storybook 进行生产环境构建，详情请看 [storybook#build](https://storybook.js.org/docs/react/api/cli-options#build)

## Storybook addon 兼容性

由于当前文档中的 Storybook 版本为 7，因此请选择 storybook V7 的 addon。

当 addon 不需要额外的 Babel 或 Webpack 配置时，可以直接使用，如 @storybook/addon-essentials。

部分 addon 需要依赖 babel 插件和 Webpack 配置时，如 @storybook/addon-coverage，只有使用 webpack 构建才会支持。

## 收益

使用 @modern-js/storybook 可以带给你 Rspack 超快的构建，并且完全无需繁琐配置，开箱即用。并且默认包含了许多 Web 构建中的最佳实践，例如 code splitting 策略，内置 css module 和 postcss，开箱即用的 TypeScript 支持，内置常用 Babel 插件等等。

Modern.js 的构建能力和配置都可以直接在 Storybook 项目中使用。

## Trouble Shooting

1. 使用 Modern.js 启动 storybook 时不会读取 babel.config.json 等配置文件，因此 babel 配置需要在 [tools.babel](/configure/app/tools/babel) 中进行配置。
   同样的 webpack 配置需要写在 [tools.webpack](/configure/app/tools/webpack) 或 [tools.webpackChain](/configure/app/tools/webpack-chain) 中。

2. 如果发现构建速度很慢，请检查是否开启了自动文档生成功能，如果想要最高的性能，请配置为 `react-docgen`。`react-docgen` 和 `react-docgen-typescript` 的区别是，前者基于 Babel 实现，后者基于 TypeScript 实现，前者性能会更好，但类型推断能力更弱。如果使用 Rspack 构建，则只支持 `react-docgen`。

```javascript filename='.storybook/main.js'
const config = {
  typescript: {
    reactDocgen: 'react-docgen',
  },
};

export default config;
```

## 迁移指南

### 从 Modern.js Storybook V6 迁移

如果你是从 V6 迁移至 V7 的用户，可以通过 [上述方式](#快速开始) 使用 V7，同时做以下调整:

##### 修改配置文件

若你在旧版本对 storybook 进行了一些自定义配置，需要将配置文件 `root/config/storybook/main.(j|t)s` 移动到 `root/.storybook/main.(j|t)s`。

并在 `root/.storybook/main.(j|t)s` 中添加以下配置，指定 framework 为 @modern-js/storybook：

```diff
const config = {
+  framework: {
+    name: '@modern-js/storybook'
+  },
};

export default config;
```

##### 依赖升级

升级 @storybook/addon-\* 系列依赖，升级到 7 版本。

##### 移除 @modern-js/plugin-storybook 插件

在 modern.config.(j|t)s 中删除 @modern-js/plugin-storybook 插件的注册。

##### 修改 Storybook 写法

按照 Storybook 官网文档，对一些 breaking change 做相应的更新，例如 stories 的写法，MDX 的写法等，参考[storybook 迁移文档](https://storybook.js.org/docs/react/migration-guide)。

### 从原生 Storybook 项目迁移

若当前 Storybook 版本还是 6，需要先按照 Storybook 官网文档升级到版本 7，参考 [storybook 迁移文档](https://storybook.js.org/docs/react/migration-guide)。

```diff filename='.storybook/main.js'
const config = {
-  framework: '@storybook/react-webapck5',
+  framework: {
+    name: '@modern-js/storybook'
+  },
};

export default config;
```

Modern.js 的配置文件默认为 `modern.config.(j|t)s`，配置请查看 [modern.js 配置](/configure/app/usage)。

若原来项目中包含了 Babel 等配置，需要对应的写在 modern 配置中，大部分 Babel 配置已经包含进了 Modern.js。

安装完成后进行相应的[配置](/guides/basic-features/debug/using-storybook#配置)。
