heroui-migration

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	フラットな props：<Card title="x">	複合コンポーネント：<Card><Card.Header>
イベントハンドラー	onClick	onPress
スタイリング	classNames prop	className prop
フック	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.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 では、フラットな props ではなく、Card.Header、Card.Title、子要素を持つ Button を使用します
3. Provider は不要：移行時に HeroUIProvider を削除します
4. onClick ではなく onPress：すべてのインタラクティブなコンポーネントで 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 ブランチのステージング環境を対象としています。ドキュメントが main にマージされ、heroui.com で公開されたら、HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration を設定するか、スクリプトのデフォルト値を更新してください。