HeroUI v2 から v3 マイグレーションガイド

このスキルは、HeroUI v2 アプリケーションを v3 にマイグレーションするのに役立ちます。HeroUI v3 では以下の重大な変更が導入されます：複合コンポーネント、Provider なし、Tailwind v4、およびフックの削除。

---

インストール

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 プロップ
フック	useSwitch、useDisclosure など	複合コンポーネント、useOverlayState
パッケージ	@heroui/system、@heroui/theme	@heroui/react、@heroui/styles

---

マイグレーションドキュメントへのアクセス

マイグレーションの詳細、例、ステップバイステップガイドについては、必ずドキュメントを取得してください：

スクリプトの使用

# 利用可能なすべてのコンポーネントマイグレーションガイドをリストアップ
node scripts/list_migration_guides.mjs

# メインのマイグレーションワークフローを取得（フルまたは段階的）
node scripts/get_migration_guide.mjs full
node scripts/get_migration_guide.mjs incremental

# コンポーネント固有のマイグレーションガイドを取得
node scripts/get_component_migration_guides.mjs button
node scripts/get_component_migration_guides.mjs button card modal

# スタイリングマイグレーションガイドを取得
node scripts/get_styling_migration_guide.mjs

# フックマイグレーションガイドを取得
node scripts/get_hooks_migration_guide.mjs

直接 URL

マイグレーションドキュメント（プレビュー）：https://heroui-git-docs-migration-heroui.vercel.app/docs/react/migration/{filename}

例：

• フルマイグレーション：.../agent-guide-full.mdx
• 段階的：.../agent-guide-incremental.mdx
• Button：.../button.mdx
• スタイリング：.../styling.mdx
• フック：.../hooks.mdx

ドキュメントが本番環境にマージされた場合、HEROUI_MIGRATION_DOCS_BASE でベース URL をオーバーライドしてください。

MCP の代替手段

Cursor または他の MCP クライアントを使用している場合、Migration MCP サーバーを構成してツールベースのアクセスを有効にしてください：

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

---

マイグレーション戦略

フルマイグレーション

• 最適：集中的に時間を確保できるプロジェクト；一時的に破損したコードに問題のないチーム
• すべてのコンポーネントコードを最初にマイグレーション（マイグレーション中はプロジェクトが破損）
• 依存関係を v3 に切り替え
• スタイリングマイグレーションを完了

段階的マイグレーション

• 最適：機能性を保つ必要があるプロジェクト；段階的にマイグレーションする大規模コードベース
• 共存をセットアップ（pnpm エイリアスまたはコンポーネントパッケージ）
• コンポーネントを1つずつマイグレーション
• マイグレーション中に v2 と v3 が共存

開始する前に必ずエージェントガイドを取得してください： node scripts/get_migration_guide.mjs full または incremental

---

コア原則

1. 最初に取得する：変更を適用する前に、スクリプトを使用してマイグレーションガイドを取得する
2. 複合コンポーネント：v3 では Card.Header、Card.Title、Button with 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. スタイリング更新を適用

---

プレビューモード

このスキルは docs/migration ブランチのステージングデプロイメントを対象としています。ドキュメントがメインにマージされて heroui.com で公開されたら、HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration を設定するか、スクリプトのデフォルトを更新してください。