heroui-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HeroUI v2 to v3 Migration Guide

HeroUI v2 迁移至v3指南

This skill helps agents migrate HeroUI v2 applications to v3. HeroUI v3 introduces breaking changes: compound components, no Provider, Tailwind v4, and removed hooks.

本指南帮助开发人员将HeroUI v2应用迁移至v3版本。HeroUI v3带来了多项破坏性变更：复合组件、无需Provider、Tailwind v4，以及移除部分hooks。

Installation

安装

bash

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

bash

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

CRITICAL: Always Fetch Migration Docs Before Applying

关键注意事项：执行迁移前务必获取迁移文档

Do NOT assume v2 patterns work in v3. Always fetch migration guides before implementing changes.

请勿假设v2的使用模式在v3中仍然有效。 在实施变更前，务必先获取迁移指南。

Key v2 → v3 Changes

v2 → v3 核心变更

Feature	v2 (Migrate From)	v3 (Migrate To)
Provider	`<HeroUIProvider>` required	No Provider needed
Component API	Flat props: `<Card title="x">`	Compound: `<Card><Card.Header>`
Event handlers	`onClick`	`onPress`
Styling	`classNames` prop	`className` prop
Hooks	`useSwitch` , `useDisclosure` , etc.	Compound components, `useOverlayState`
Packages	`@heroui/system` , `@heroui/theme`	`@heroui/react@beta` , `@heroui/styles@beta`

特性	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@beta` , `@heroui/styles@beta`

Accessing Migration Documentation

查阅迁移文档

For migration details, examples, and step-by-step guides, always fetch documentation:

如需迁移细节、示例及分步指南，请务必查阅文档：

Using Scripts

使用脚本

bash

undefined

bash

undefined

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

获取Hooks迁移指南

node scripts/get_hooks_migration_guide.mjs

undefined

node scripts/get_hooks_migration_guide.mjs

undefined

Direct URLs

直接URL

Migration docs (preview):

https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}

Examples:

Full migration:
```
.../agent-guide-full.mdx
```
Incremental:
```
.../agent-guide-incremental.mdx
```
Button:
```
.../button.mdx
```
Styling:
```
.../styling.mdx
```
Hooks:
```
.../hooks.mdx
```

Override base URL with

HEROUI_MIGRATION_DOCS_BASE

when docs are merged to production.

迁移文档（预览版）：

https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}

示例：

完整迁移：
```
.../agent-guide-full.mdx
```
增量迁移：
```
.../agent-guide-incremental.mdx
```
按钮组件：
```
.../button.mdx
```
样式迁移：
```
.../styling.mdx
```
Hooks迁移：
```
.../hooks.mdx
```

当文档合并到生产环境时，可通过

HEROUI_MIGRATION_DOCS_BASE

覆盖基础URL。

MCP Alternative

MCP替代方案

When using Cursor or other MCP clients, configure the Migration MCP server for tool-based access:

json

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

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

json

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

Migration Strategies

迁移策略

Full Migration

完整迁移

Best for: Projects that can dedicate focused time; teams comfortable with temporarily broken code
Migrate all component code first (project broken during migration)
Switch dependencies to v3
Complete styling migration

适用场景：可投入集中时间的项目；团队能够接受代码暂时处于不可用状态
先迁移所有组件代码（迁移期间项目不可用）
切换依赖至v3版本
完成样式迁移

Incremental Migration

增量迁移

Best for: Projects that must stay functional; large codebases migrating gradually
Set up coexistence (pnpm aliases or component packages)
Migrate components one-by-one
Both v2 and v3 coexist during migration

Always fetch the agent guide before starting:

node scripts/get_migration_guide.mjs full

incremental

适用场景：必须保持可用的项目；大型代码库逐步迁移
设置共存环境（pnpm别名或组件包）
逐个迁移组件
迁移期间v2和v3版本共存

开始前务必获取官方指南：

node scripts/get_migration_guide.mjs full

或

incremental

Core Principles

核心原则

Fetch first: Use scripts to get migration guides before applying changes
Compound components: v3 uses
```
Card.Header
```
,
```
Card.Title
```
,
```
Button
```
with children—not flat props
No Provider: Remove
```
HeroUIProvider
```
when migrating
onPress not onClick: All interactive components use
```
onPress
```
Workflow: Analyze → Migrate components → Switch deps → Styling migration

先获取文档：在实施变更前，使用脚本获取迁移指南
复合组件：v3使用
```
Card.Header
```
、
```
Card.Title
```
、
```
Button
```
结合子元素——而非扁平属性
无需Provider：迁移时移除
```
HeroUIProvider
```
使用onPress而非onClick：所有交互组件均使用
```
onPress
```
工作流：分析 → 迁移组件 → 切换依赖 → 样式迁移

Migration Workflow Summary

迁移工作流总结

Create migration branch
Analyze project (HeroUI imports, component usage)

Fetch main guide:

node scripts/get_migration_guide.mjs full

Migrate components in batches (fetch component guides per batch)
Switch dependencies to v3

Fetch styling guide:

node scripts/get_styling_migration_guide.mjs

Apply styling updates

创建迁移分支
分析项目（HeroUI导入、组件使用情况）

获取主指南：

node scripts/get_migration_guide.mjs full

批量迁移组件（每批组件需获取对应指南）
切换依赖至v3版本

获取样式指南：

node scripts/get_styling_migration_guide.mjs

应用样式更新

Preview Mode

预览模式

This skill targets the staging deployment of the

docs/migration

branch. Once docs are merged to main and live on v3.heroui.com, set

HEROUI_MIGRATION_DOCS_BASE=https://v3.heroui.com/docs/react/migration

or update the default in scripts.

本指南针对

docs/migration

分支的预发布部署。一旦文档合并至主分支并在v3.heroui.com上线，设置

HEROUI_MIGRATION_DOCS_BASE=https://v3.heroui.com/docs/react/migration

或更新脚本中的默认值。