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.
Security Assessment
Detected risks:
About heroui-migration
The HeroUI Migration skill is a specialized guide designed to help AI agents and developers migrate applications from HeroUI v2 to v3. HeroUI v3 introduces significant breaking changes including the shift to compound components, removal of the Provider requirement, adoption of Tailwind v4, and deprecation of various hooks. This skill ensures agents follow correct migration patterns by always fetching official documentation before applying changes, preventing assumptions that v2 patterns will work in v3.
The skill provides comprehensive access to migration documentation through multiple methods: Node.js scripts for fetching guides, direct URLs to preview documentation, and MCP server integration for tool-based access. It covers all critical migration aspects including component API changes (flat props to compound components), event handler updates (onClick to onPress), styling transitions (classNames to className), package restructuring, and hook replacements. The documentation includes detailed guides for individual components like Button, Card, and Modal, as well as specialized guides for styling and hooks migration.
This skill is ideal for development teams working with HeroUI-based applications who need to upgrade to v3, whether they prefer a full migration approach (migrating everything at once) or an incremental strategy (gradual migration with v2 and v3 coexisting). It's particularly valuable for AI coding agents that need structured guidance to avoid hallucinating incorrect migration patterns and for teams managing large codebases that must remain functional during the migration process.
FAQ
What are the main breaking changes between HeroUI v2 and v3?
HeroUI v3 introduces several breaking changes: compound components replace flat props (e.g., <Card><Card.Header> instead of <Card title="x">), the HeroUIProvider is no longer needed, event handlers changed from onClick to onPress, styling uses className instead of classNames prop, and many hooks have been removed in favor of compound components or useOverlayState.
Should I use full migration or incremental migration?
Full migration is best for projects that can dedicate focused time and are comfortable with temporarily broken code during migration. Incremental migration is recommended for projects that must stay functional throughout the process, large codebases, or teams migrating gradually. The incremental approach uses pnpm aliases or component packages to allow v2 and v3 to coexist.
How do I access the migration documentation?
You can access migration docs through three methods: 1) Node.js scripts (list_migration_guides.mjs, get_migration_guide.mjs, get_component_migration_guides.mjs), 2) Direct URLs to the preview site at heroui-git-docs-migration-heroui.vercel.app, or 3) MCP server integration for Cursor and other MCP clients. Always fetch documentation before implementing changes.
Do I need to install anything to use this skill?
Yes, install the skill using: curl -fsSL https://heroui.com/install | bash -s heroui-migration. The skill includes Node.js scripts for fetching documentation and requires access to the migration documentation URLs or MCP server configuration.
Can v2 and v3 components coexist in the same project?
Yes, using the incremental migration strategy. You can set up coexistence through pnpm aliases or separate component packages, allowing you to migrate components one-by-one while keeping your application functional. This approach is recommended for large codebases that cannot afford downtime during migration.
Install heroui-migration
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
heroui-inc/heroui