heroui-migration

HeroUI v2 到 v3 迁移指南

本 Skill 帮助 Agent 将 HeroUI v2 应用迁移到 v3。HeroUI v3 引入了多项破坏性变更：复合组件、无需 Provider、Tailwind v4，以及移除的 Hooks。

---

安装

curl -fsSL https://heroui.com/install | bash -s heroui-migration

---

重要：应用前务必先获取迁移文档

不要假设 v2 的写法在 v3 中仍然有效。 在实施变更前，务必先获取迁移指南。

主要的 v2 → v3 变更

功能	v2（迁移前）	v3（迁移后）
Provider	必须使用 <HeroUIProvider>	无需 Provider
组件 API	扁平属性：<Card title="x">	复合式：<Card><Card.Header>
事件处理器	onClick	onPress
样式	classNames 属性	className 属性
Hooks	useSwitch、useDisclosure 等	复合组件、useOverlayState
包	@heroui/system、@heroui/theme	@heroui/react、@heroui/styles

---

访问迁移文档

如需迁移细节、示例和分步指南，请务必获取文档：

使用脚本

# List all available component migration guides
node scripts/list_migration_guides.mjs

# Get main migration workflow (full or incremental)
node scripts/get_migration_guide.mjs full
node scripts/get_migration_guide.mjs incremental

# Get component-specific migration guides
node scripts/get_component_migration_guides.mjs button
node scripts/get_component_migration_guides.mjs button card modal

# Get styling migration guide
node scripts/get_styling_migration_guide.mjs

# Get hooks migration guide
node scripts/get_hooks_migration_guide.mjs

直接 URL

迁移文档（预览版）：请使用下方示例中的具体指南 URL，切勿获取仍包含占位符的 URL。

示例：

• 完整迁移：.../agent-guide-full.mdx
• 增量迁移：.../agent-guide-incremental.mdx
• Button：.../button.mdx
• 样式：.../styling.mdx
• Hooks：.../hooks.mdx

当文档合并到生产环境时，可通过 HEROUI_MIGRATION_DOCS_BASE 覆盖基础 URL。

MCP 替代方案

使用 Cursor 或其他 MCP 客户端时，可配置 Migration MCP 服务以通过工具访问：

{
  "mcpServers": {
    "heroui-migration": {
      "url": "https://migration-mcp.heroui.com"
    }
  }
}

---

迁移策略

完整迁移

• 适用于：可以集中时间投入的项目；团队能接受临时出现损坏代码的情况
• 先迁移所有组件代码（迁移期间项目无法正常运行）
• 切换依赖到 v3
• 完成样式迁移

增量迁移

• 适用于：必须保持可用的项目；大型代码库逐步迁移
• 设置共存方案（pnpm 别名或组件包）
• 逐个迁移组件
• 迁移期间 v2 和 v3 并存

开始前务必获取 Agent 指南： node scripts/get_migration_guide.mjs full 或 incremental

---

核心原则

1. 先获取：在应用变更前，使用脚本获取迁移指南
2. 复合组件：v3 使用 Card.Header、Card.Title，Button 通过 children 传入内容，而非扁平属性
3. 无 Provider：迁移时移除 HeroUIProvider
4. 使用 onPress 而非 onClick：所有交互组件都使用 onPress
5. 工作流：分析 → 迁移组件 → 切换依赖 → 样式迁移

---

迁移工作流摘要

1. 创建迁移分支
2. 分析项目（HeroUI 导入、组件使用情况）
3. 获取主指南：node scripts/get_migration_guide.mjs full
4. 分批迁移组件（每批获取对应组件指南）
5. 切换依赖到 v3
6. 获取样式指南：node scripts/get_styling_migration_guide.mjs
7. 应用样式更新

---

预览模式

本 Skill 针对 docs/migration 分支的预发布部署。文档合并到 main 并在 heroui.com 上线后，可设置 HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration，或更新脚本中的默认值。