Modern.js 项目中 Storybook 的完整使用指南

前言

Storybook 作为当下最流行的组件开发工具，为前端开发者提供了强大的组件隔离开发环境。本文将详细介绍如何在 Modern.js 项目中高效使用 Storybook，涵盖从基础配置到高级特性的完整工作流程。

Storybook 核心价值

Storybook 为组件开发带来诸多优势：

1. 独立开发环境：每个组件可以在隔离环境中开发和测试
2. 可视化调试：直观展示组件在不同状态下的表现
3. 文档一体化：组件文档与实现保持同步更新
4. 协作效率：方便团队成员共享和讨论组件设计

Modern.js 集成方案

Modern.js 提供了两种 Storybook 集成方式：

推荐方案：Storybook V7

初始化配置

执行以下命令快速启用 Storybook V7：

npx modern new

选择启用 Storybook V7 功能后，Modern.js 会自动完成：

• 创建 .storybook 配置目录
• 添加必要的依赖项
• 生成示例 stories 文件
• 配置 package.json 脚本

开发工作流

Modern.js 推荐的工作流是：

1. 启动构建监听模式：modern build --watch
2. 在 stories 中直接引用组件产物
3. 启动 Storybook 开发服务器

这种分离构建的方式解决了 esbuild 和 Webpack 配置不兼容的问题。

类型定义处理

针对类型定义同步问题，Modern.js 提供了不同包管理器的解决方案：

• pnpm 项目：通过 publishConfig 区分开发和生产类型定义
• npm/Yarn 项目：需要手动切换 types 字段

Rspack 加速构建

Modern.js 支持使用 Rspack 替代 Webpack 以获得更快的构建速度，只需简单配置：

// .storybook/main.js
{
  framework: {
    options: {
      bundler: 'rspack'
    }
  },
  typescript: {
    reactDocgen: 'react-docgen'
  }
}

高级配置

Modern.js 通过 Rsbuild 提供构建能力，支持通过 builderConfig 进行深度定制：

// .storybook/main.js
{
  framework: {
    options: {
      builderConfig: {
        alias: {
          react: require.resolve('react')
        }
      }
    }
  }
}

传统方案：Storybook V6（已弃用）

虽然 Modern.js 仍支持 V6，但建议新项目直接使用 V7。V6 的主要特点是：

• 配置文件位于 config/storybook 目录
• 存在一些配置限制（如不能修改 stories 位置）
• 使用专用命令进行构建和开发

迁移指南

从 V6 迁移到 V7 需要以下步骤：

1. 配置文件迁移：将配置从 config/storybook 移动到 .storybook
2. 依赖更新：升级 Storybook 相关依赖到 V7 版本
3. 命令替换：使用标准 Storybook 命令替代 Modern.js 专用命令
4. 配置清理：移除 Modern.js 插件相关配置

最佳实践

1. 组件开发流程：

   • 先编写组件基础实现
   • 创建对应 stories 展示各种状态
   • 通过 Storybook 交互式测试
   • 完善组件文档

2. 性能优化：

   • 优先使用 Rspack 构建
   • 合理组织 stories 结构
   • 利用 Modern.js 的按需加载能力

3. 团队协作：

   • 将 Storybook 部署为静态站点共享
   • 利用 Chromatic 等工具进行可视化测试
   • 建立组件开发规范

总结

Modern.js 深度集成了 Storybook，大幅降低了配置复杂度，让开发者可以专注于组件开发本身。通过本文介绍的工作流和最佳实践，开发者可以高效利用 Storybook 提升组件开发质量和团队协作效率。