使用 Storybook#

Storybook 是一个专门用于组件调试的工具，它围绕着组件开发提供了：

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

快速开始#

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

$ 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 作为构建工具。

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

用于指定配置文件路径。

例如

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

export default config;

bundler#

• 类型: 'webpack' | 'rspack'
• 默认值: webpack

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

例如

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

export default config;

builderConfig#

• 类型: BuilderConfig
• 默认值: undefined

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

例如

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

storybook build#

对 Storybook 进行生产环境构建，详情请看 storybook#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 中进行配置。 同样的 webpack 配置需要写在 tools.webpack 或 tools.webpackChain 中。

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

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：

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 迁移文档。

从原生 Storybook 项目迁移#

若当前 Storybook 版本还是 6，需要先按照 Storybook 官网文档升级到版本 7，参考 storybook 迁移文档。

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

export default config;

Modern.js 的配置文件默认为 modern.config.(j|t)s，配置请查看 modern.js 配置。

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

安装完成后进行相应的配置。