heroui-migration

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"} 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 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 # 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 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 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 Preview Mode This skill targets the staging deployment of the docs/migration branch. Once docs are merged to main and live on heroui.com, set HEROUI_MIGRATION_DOCS_BASE=https://heroui.com/docs/react/migration or update the default in scripts.