Modern.js 项目中集成 Storybook 的完整指南

前言

在现代前端开发中，组件化开发已成为主流模式。作为开发者，我们需要高效的工具来调试、测试和展示组件。Storybook 正是这样一款优秀的工具，而 Modern.js 提供了与 Storybook 深度集成的解决方案，让组件开发体验更加流畅。

Storybook 简介

Storybook 是一个专门用于 UI 组件开发的工具，它为前端团队提供了：

1. 组件隔离环境：独立于主应用开发和测试组件
2. 可视化调试：直观地查看组件在不同状态下的表现
3. 文档生成：自动生成组件使用文档
4. 协作工具：方便团队成员共享和讨论组件

Modern.js 与 Storybook 集成优势

Modern.js 深度整合了 Storybook，带来以下显著优势：

1. 零配置体验：自动处理 Webpack/Rspack、Babel 等复杂配置
2. 构建工具选择：支持 Webpack 和 Rspack 两种构建引擎
3. 性能优化：特别是 Rspack 带来的极速构建体验
4. 统一配置：与 Modern.js 项目配置保持一致

三种集成场景详解

场景一：全新 Modern.js 项目集成 Storybook

这是最简单的场景，Modern.js 提供了开箱即用的支持：

1. 执行命令启用 Storybook 功能：

npx modern new

选择启用 Storybook V7 功能

2. 自动创建的文件结构：

.storybook/
  ├── main.ts       # Storybook 主配置
  └── preview.ts    # Storybook 预览配置
stories/            # 示例组件目录

3. 添加的 npm 脚本：

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}

场景二：从旧版迁移到 Modern.js Storybook

迁移步骤需要特别注意：

1. 配置文件位置变更：

   • 旧位置：root/config/storybook/main.(j|t)s
   • 新位置：root/.storybook/main.(j|t)s

2. 必须添加的框架配置：

framework: {
  name: '@modern-js/storybook'
}

3. 依赖升级：
   • 所有 @storybook/addon-* 包需要升级到 V7 版本
   • 移除旧版 @modern-js/plugin-storybook

场景三：原生 Storybook 项目接入 Modern.js

对于已有 Storybook 项目，接入 Modern.js 需要：

1. 确保 Storybook 版本为 7+
2. 修改框架配置：

framework: {
  name: '@modern-js/storybook'
}

3. 创建 Modern.js 配置文件 modern.config.(j|t)s

构建引擎选择与配置

Modern.js 支持两种构建引擎，各有特点：

Webpack 引擎

• 优势：成熟稳定，插件生态丰富
• 适用场景：需要复杂自定义配置的项目
• 安装：

npm install @modern-js/builder-webpack-provider

Rspack 引擎

• 优势：极速构建，开发体验流畅
• 注意：某些高级功能可能受限
• 安装：

npm install @modern-js/builder-rspack-provider

配置示例：

framework: {
  name: '@modern-js/storybook',
  options: {
    bundler: 'rspack'
  }
},
typescript: {
  reactDocgen: 'react-docgen'  // Rspack 必须使用 react-docgen
}

高级配置指南

自定义配置文件路径

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

直接配置 Builder

framework: {
  name: '@modern-js/storybook',
  options: {
    builderConfig: {
      alias: {
        'react': require.resolve('react')
      },
      output: {
        assetPrefix: '/assets/'
      }
    }
  }
}

使用 Builder 插件

import { defineConfig } from '@modern-js/storybook';
import { builderPluginSwc } from '@modern-js/builder-plugin-swc';

export default defineConfig({
  builderPlugins: [builderPluginSwc()]
});

常见问题解决方案

构建速度慢

1. 检查是否使用了合适的 reactDocgen 类型：

typescript: {
  reactDocgen: 'react-docgen'  // 性能更好
}

2. 考虑切换到 Rspack 构建引擎

插件兼容性问题

1. 确保使用 Storybook V7 版本的插件
2. 需要复杂构建配置的插件（如 @storybook/addon-coverage）：
   • 只能使用 Webpack 引擎
   • 可能需要额外配置

配置不生效

1. 确保没有遗留的 babel.config.json 或 webpack.config.js
2. 所有构建配置应通过 Modern.js 配置文件设置：
   • Babel 配置：tools.babel
   • Webpack 配置：tools.webpack 或 tools.webpackChain

最佳实践建议

1. 项目结构：

   • 将 stories 放在组件同级目录
   • 使用 CSF (Component Story Format) 格式编写 stories

2. 性能优化：

   • 开发环境使用 Rspack
   • 生产构建使用 Webpack（如需更多优化）

3. 文档生成：

   • 为每个组件编写清晰的 JSDoc
   • 使用 ArgsTable 展示组件属性

4. 测试集成：

   • 结合 @storybook/testing-library 进行交互测试
   • 使用 @storybook/jest 进行快照测试

结语

Modern.js 与 Storybook 的深度集成为前端组件开发带来了全新的体验。通过本文的指南，开发者可以快速搭建高效的组件开发环境，充分利用 Modern.js 提供的优化和 Storybook 的强大功能，大幅提升组件开发效率和质量。