使用 Storybook#

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

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

在使用 Storybook 时，难免会遇到各种配置问题，需要手动配置 Babel 插件，手动配置 Webpack 去支持 less，sass 等。 Modern.js 集成了 Storybook，这对于我们开发 Storybook 项目来说极大地简化了配置工作。

V7 (推荐)#

开启 Storybook#

可以直接使用如下命令开启 Storybook 功能。

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

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

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

开启产物调试#

事实上，Modern.js Module 是基于 esbuild 实现的，而 Storybook 使用 Webpack 作为默认构建工具，二者的配置无法完全兼容， 所以这里我们推荐先对组件进行构建，然后在 stories 里引入组件产物。

引入组件产物的方式非常简单，假设你的模块导出了一个 Button 组件，那么在 stories 里可以这样使用:

import { Button } from '.';

export const YourStory = () => <Button />;

export default {
  title: 'Your Stories',
};

如果想要更新组件，则可以在启动 Storybook 前启动监听模式的构建：

modern build --watch

{
    "name": "foo",
    "main": "./dist/index.js",
    "types": "./src/index.ts",
    "publishConfig": {
      "types": "./dist/index.d.ts",
    }
}

开启 Rspack 构建#

Rspack 构建速度非常快，只需要如下配置即可使用 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 中包含一些独有的配置。

bundler#

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

指定底层打包工具使用 Webpack 还是 Rspack。

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

export default config;

builderConfig#

• 类型: BuilderConfig
• 默认值: undefined

Modern.js 的 Storybook 构建能力由 Rsbuild 提供，可通过 builderConfig 修改 Rsbuild 构建配置。

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 build#

对 Storybook 进行生产环境构建，查看详情

配置文件#

配置文件中除了 Rsbuild 配置还包含一个额外的字段，builderPlugins，方便使用 Rsbuild 插件，例如启用 SWC 编译。

import { defineConfig } from '@modern-js/storybook';
import { pluginSwc } from '@rsbuild/plugin-webpack-swc';

const config = defineConfig({
  builderPlugins: [pluginSwc()],
});

export default config;

从 V6 迁移至 V7#

我们对于两个版本的支持方式不同，因此如果你是从 V6 迁移至 V7 的用户，我们希望你也按上述方式使用 V7，同时做以下调整:

• 配置文件：将原来 root/config/storybook/main.(j|t)s 里的自定义配置（如果有）迁移到新的 root/.storybook/main.(j|t)s。
• 依赖：升级 @storybook/addon-* 系列依赖（如果有）到 7 版本，并删除 @modern-js/plugin-storybook 依赖。
• 命令: 将原来 edenx dev storybook 和 edenx build --platform 命令删除，如果习惯了原来的 pnpm run dev 的调用方式，可以 将其替换成 storybook dev -p 6006 和 storybook build。
• modern.config.(j|t)s : 删除 @modern-js/plugin-storybook 插件的注册。

V6 (legacy)#

从 2.40.0 版本开始，@modern-js/plugin-storybook将停止迭代。建议使用 V7 版本。 如果你的 @modern-js/module-tools 版本低于 2.40.0，可以按照以下方式使用 Storybook V6:

开启 Storybook#

可以直接使用如下命令开启 Storybook 功能。

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

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

• 创建 stories 组件示例
• 更新 package.json，新增依赖 @modern-js/plugin-storybook，以及添加 pnpm dev storybook 等相关脚本。

配置 Storybook#

Storybook 官方通过一个名为 .storybook 的文件夹来进行项目配置，其中包含各种配置文件。在 Modern.js Module 中，可以在项目的 config/storybook 目录下增加 Storybook 配置文件。

关于 Storybook 各种配置文件的使用方式，可以查看下面的链接：

• Configure Storybook

不过这在模块项目里使用时存在一些限制：

• 不能修改 Story 文件存放的位置，即无法在 main.js 文件里修改 stories 配置。
• 不能修改 Webpack 和 Babel 相关的配置，即无法在 main.js 文件里修改 webpackFinal 和 babel 配置。

构建 Storybook 产物#

除了可以对组件或者普通的模块进行 Storybook 调试，还可以通过下面的命令来执行 Storybook 的构建任务。

modern build --platform storybook

构建完成后，可以在 dist/storybook-static 目录看到构建产物文件。