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

前言

在现代前端开发中，组件化开发已经成为主流模式。Storybook 作为一款强大的组件开发工具，能够帮助开发者更好地构建、测试和展示 UI 组件。本文将详细介绍如何在 Modern.js 项目中高效使用 Storybook。

Storybook 核心价值

Storybook 为组件开发提供了全方位的支持：

1. 可视化调试：独立运行组件，无需嵌入实际应用
2. 文档生成：自动为组件生成可交互的文档
3. 测试集成：支持与各种测试工具无缝集成
4. 协作分享：便于团队协作和设计验收
5. 开发效率：提供热更新等提升开发体验的功能

Modern.js 集成优势

传统 Storybook 配置复杂，Modern.js 提供了开箱即用的集成方案：

• 自动处理 Babel/Webpack 配置
• 内置对 Sass/Less 等预处理器的支持
• 简化项目初始化流程
• 提供优化的构建配置

推荐使用 Storybook V7

初始化配置

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

npx modern new

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

1. 创建 .storybook 配置目录
2. 生成示例组件和 stories
3. 添加必要的依赖项
4. 配置 package.json 脚本

开发工作流

Modern.js 推荐的最佳实践是：

1. 使用 modern build --watch 监听组件变更
2. 在 stories 中引用构建后的组件产物

这种分离构建的方式确保了类型安全和构建效率的最佳平衡。

类型定义优化

对于使用 pnpm 的项目，可以通过配置 package.json 确保开发时获得正确的类型提示：

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

性能优化：使用 Rspack

Modern.js 支持使用 Rspack 替代 Webpack 以获得更快的构建速度：

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

注意：使用 Rspack 时需要调整 reactDocgen 配置。

高级配置

Modern.js 提供了灵活的配置选项：

1. bundler：选择 Webpack 或 Rspack
2. builderConfig：自定义 Rsbuild 配置
3. builderPlugins：扩展构建能力

示例配置：

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

从 V6 迁移到 V7

迁移步骤包括：

1. 配置文件迁移：从 config/storybook 移动到 .storybook
2. 依赖更新：升级 Storybook 相关依赖到 V7 版本
3. 命令替换：使用新的 Storybook CLI 命令
4. 配置清理：移除旧的插件注册

遗留版本 (V6)

对于仍在使用 V6 版本的项目，Modern.js 提供了兼容支持：

1. 通过 modern new 命令启用 Storybook
2. 在 config/storybook 目录下进行配置
3. 使用 modern build --platform storybook 构建

最佳实践建议

1. 组件组织：按功能模块组织 stories
2. 文档规范：为每个组件编写详细的文档
3. 测试集成：结合 Storybook 的测试能力
4. 主题定制：根据项目需求定制 Storybook 主题
5. 性能监控：关注构建和运行时性能

结语

Modern.js 与 Storybook 的深度集成为组件驱动开发提供了强大支持。通过本文介绍的方法，开发者可以快速搭建高效的组件开发环境，提升开发体验和组件质量。建议新项目直接采用 V7 版本，以获得最佳的功能支持和性能表现。