Heroui Migration
Migrate an existing HeroUI v2 React app to v3 without guessing breaking API, styling, and packaging changes.
Overview
heroui-migration is an agent skill for the Build phase that guides HeroUI v2→v3 upgrades using fetched official migration documentation before code changes.
Install
npx skills add https://github.com/heroui-inc/heroui --skill heroui-migrationWhat is this skill?
- Forces fetching official migration docs before applying v2 patterns in v3
- Documents v2→v3 breaking shifts: no HeroUIProvider, compound components, onPress vs onClick
- Covers Tailwind v4, className vs classNames, and hook removals with useOverlayState
- Installs via heroui.com curl installer for agent-accessible migration workflow
- Explicit preview-status skill metadata (v2.0.0) for version-aware upgrades
- Explicit v2→v3 comparison table for Provider, compound API, onPress, className, hooks, and packages
Adoption & trust: 1.8k installs on skills.sh; 29.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your React app still uses HeroUI v2 patterns while v3 expects compound components, different events, and no global provider.
Who is it for?
Solo builders maintaining a HeroUI-based React UI who are bumping major versions and want agents to follow the real migration guide.
Skip if: Greenfield apps already scaffolded on HeroUI v3 with no legacy v2 imports, or teams not using HeroUI at all.
When should I use this skill?
Migrating HeroUI v2 apps to v3, upgrading components, or when agents need HeroUI migration documentation keywords.
What do I get? / Deliverables
Your codebase aligns with v3 APIs, Tailwind v4 conventions, and compound layouts so UI work can continue without silent regressions.
- v3-aligned component refactors (compound structure, onPress, className)
- Removed obsolete HeroUIProvider and deprecated hook usage
Recommended Skills
Journey fit
UI library upgrades happen while you are actively building or refactoring the product frontend, not during idea or launch distribution work. HeroUI is a component layer on Tailwind—migration tasks map directly to frontend component and theme refactors.
How it compares
Use this focused migration skill instead of generic React upgrade chat that will hallucinate v2-compatible HeroUI APIs.
Common Questions / FAQ
Who is heroui-migration for?
Indie and solo React developers who ship with HeroUI and need agents to upgrade v2 codebases to v3 without breaking compound components or styling.
When should I use heroui-migration?
During Build (frontend) when upgrading dependencies, refactoring cards and overlays, or anytime SKILL.md says to fetch migration docs before editing HeroUI components.
Is heroui-migration safe to install?
Review the Security Audits panel on this Prism page and treat the curl installer like any third-party script—verify URLs and repo trust before running in CI or locally.
SKILL.md
READMESKILL.md - Heroui Migration
# 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 ```bash curl -fsSL https://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. ### 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 ```bash # 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): `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. ### MCP Alternative 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" } } } ``` --- ## 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 bra