Skip to content
Development
Skill

/heroui-migration

HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI.

From plugin
claude-codex-settings
1.2k112 skills4 agents5 commands4 MCP

Claude Code

$ npx -y skills add fcakyon/claude-codex-settings --skill heroui-migration --agent claude-code

SKILL.md

heroui-migration.SKILL.md
name: heroui-migration
description: "HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI."
metadata:
  author: heroui
  version: "2.0.0"
  status: preview

> Marketplace adaptation: installation and framework guidance follow the host project.

HeroUI v2 to v3 Migration Guide

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

---

Installation

This skill is provided by the marketplace plugin. Install project dependencies using the host project package manager.

---

CRITICAL: Always Fetch Migration Docs Before Applying

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

Key v2 → v3 Changes

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

---

Accessing Migration Documentation

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

Using Scripts

# 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

Direct URLs

Migration docs (preview): use a concrete guide URL from the examples below, and never fetch a URL that still contains a placeholder.

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.

MCP Alternative

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

{
  "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

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` or `incremental`

---

Core Principles

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

---

Migration Workflow Summary

1. Create migration branch 2. Analyze project (HeroUI imports, component usage) 3. Fetch main guide: `node scripts/get_migration_guide.mjs full` 4. Migrate components in batches (fetch component guides per batch) 5. Switch dependencies to v3 6. Fetch styling guide: `node scripts/get_styling_migration_guide.mjs` 7. Apply styling updates

---

Documentation source

The bundled scripts use the production migration documentation at https://heroui.com/en/docs/react/migration. Set HEROUI_MIGRATION_DOCS_BASE only when a different documentation deployment is required.

Read more
@fcakyon
Ships withclaude-codex-settings

Battle-tested Claude Code, OpenAI Codex, Cursor configs, plugins, hooks and agents with Kimi, MiniMax and GLM API support.

1.2k112 skills4 agents4 MCP
Get the whole plugin

Stars on GitHub

Momentum

stars in total
1.2k
Star history of fcakyon/claude-codex-settings on GitHub, a chart by star-history.com

Other skills on claude-codex-settings.

aeo

aeo

This skill should be used when the user asks to "build an AEO strategy", "improve AI search visibility", "track buyer prompts",…

dogfood

dogfood

Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA",…

electron

electron

Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools…

More skills from other plugins.

brainstorming
Auto-invoked

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…

@obra@obraInstall Skill
ask-matt

ask-matt

Ask which skill or flow fits your situation. A router over the skills in this repo.

skills2w309k
@mattpocock@mattpocockInstall Skill
accessibility
Auto-invoked

accessibility

Design, implement, and audit accessible UI to WCAG 2.2 Level AA across Web, iOS, and Android — semantic ARIA roles and labels,…

ecc2w293k
@affaan-m@affaan-mInstall Skill
compiler-commit

compiler-commit

Use when you want to verify compiler changes and commit with the correct convention. Runs tests, lint, and format, then commits…

react6d252k
@facebook@facebookInstall Skill

Questions about heroui-migration.

Which coding agents can use heroui-migration?
heroui-migration installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.