Modern.js 项目中 Storybook 的集成与使用指南

前言

在现代前端开发中，组件化开发已成为主流趋势。作为一款优秀的组件开发工具，Storybook 能够帮助开发者更好地开发、测试和文档化 UI 组件。Modern.js 项目对 Storybook 进行了深度集成，大大简化了配置流程，让开发者能够更专注于组件开发本身。

Storybook 简介

Storybook 是一个专门用于组件调试的工具，围绕组件开发提供了一系列强大功能：

• 开发更健壮的 UI 组件
• 以更少的工作量测试 UI，避免不稳定测试
• 为团队记录可复用的 UI 组件
• 展示 UI 的实际工作方式
• 自动化 UI 工作流程

传统使用 Storybook 时，开发者常需要处理各种配置问题，包括 Babel、Webpack、Less/Sass 等。Modern.js 的集成解决了这些问题，让 Storybook 的使用变得更加简单。

推荐使用 Storybook V7

启用 Storybook 功能

在 Modern.js 项目中启用 Storybook V7 非常简单：

npx modern new

选择 "Enable features" 操作，然后选择 "Enable「Storybook」V7" 功能。这条命令会自动完成以下工作：

1. 创建 .storybook 配置文件夹和默认配置文件 .storybook/main.ts
2. 生成示例 story 组件
3. 更新 package.json，添加必要的依赖项和脚本

开发调试技巧

由于 Modern.js Module 基于 esbuild 实现，而 Storybook 默认使用 Webpack，两者的配置并不完全兼容。我们推荐以下开发流程：

1. 先构建组件
2. 在 stories 中导入组件输出

示例代码：

import { Button } from '.';  // 导入构建后的组件

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

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

开发过程中，建议先启动构建的 watch 模式：

modern build --watch

类型定义实时更新问题

开发时可能会遇到类型定义无法实时更新的情况。针对不同包管理器的解决方案：

pnpm 项目： 修改 package.json：

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

npm/Yarn 项目： 需要在开发和发布阶段手动修改 package.json 中的 types 字段。

使用 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'
  }
};

注意：Rspack 目前不支持 @storybook/react-docgen-typescript-plugin，因此需要调整 reactDocgen 配置。

配置详解

主要配置项

1. bundler：

   • 类型：'webpack' | 'rspack'
   • 默认值：webpack
   • 指定底层构建工具

2. builderConfig：

   • 类型：BuilderConfig
   • 默认值：undefined
   • 用于修改 Rsbuild 配置

示例配置：

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

常用命令

1. storybook dev：启动 Storybook 开发服务器
2. storybook build：构建生产环境的 Storybook

从 V6 迁移到 V7

Modern.js 对两个版本的支持方式不同，迁移时需要注意：

1. 配置文件：将原 root/config/storybook/main.(j|t)s 中的自定义配置迁移到 root/.storybook/main.(j|t)s
2. 依赖项：
   • 升级 @storybook/addon-* 系列依赖到 V7 版本
   • 删除 @modern-js/plugin-storybook 依赖
3. 命令：
   • 删除原 edenx dev storybook 和 edenx build --platform 命令
   • 替换为 storybook dev -p 6006 和 storybook build
4. 配置文件：从 modern.config.(j|t)s 中移除 @modern-js/plugin-storybook 插件注册

旧版 Storybook V6 支持

从 MAJOR_VERSION.40.0 版本开始，@modern-js/plugin-storybook 将停止迭代。如果仍在使用旧版，可通过以下方式使用：

启用方式

npx modern new

选择 "Enable optional features"，然后选择 "Enable Storybook"。

配置限制

在 Modern.js Module 中使用 Storybook V6 时有一些限制：

1. 不能修改 Story 文件的存储位置（无法修改 main.js 中的 stories 配置）
2. 不能修改与 Webpack 和 Babel 相关的配置（无法修改 main.js 中的 webpackFinal 和 babel 配置）

构建命令

modern build --platform storybook

构建完成后，可在 dist/storybook-static 目录中查看输出文件。

结语

Modern.js 对 Storybook 的深度集成大大简化了前端组件开发的调试和文档化流程。无论是选择最新的 V7 版本还是继续使用 V6 版本，Modern.js 都提供了完善的解决方案。建议开发者尽快迁移到 V7 版本，以获得更好的开发体验和长期支持。