heroui-migration
This skill guides agents through upgrading HeroUI v2 applications to v3, addressing breaking changes like compound components, removed Provider requirements, and event handler renaming. It provides migration workflows for both full and incremental approaches, component-specific guides, and styling updates to keep projects functional during the transition.
heroui-migration helps you upgrade HeroUI v2 apps to v3 with guided component changes and dependency updates.
AI-generated summary based on this skill's SKILL.md
Install
heroui-inc/heroui/heroui-migration · repository language: MDX
git clone https://github.com/heroui-inc/heroui
cp -r heroui/skills/heroui-migration ~/.claude/skills/heroui-migrationnpx skillfed install heroui-inc/heroui/heroui-migrationFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I upgrade HeroUI from v2 to v3?
HeroUI-migration guides you through upgrading HeroUI from v2 to v3 with step-by-step instructions. Start by updating your package dependencies, then address breaking changes like removing the Provider wrapper, updating event handlers from onClick to onPress, and migrating to compound components. The skill supports both full migration (all at once) and incremental migration (component by component) strategies based on your project needs.
What are the main breaking changes in HeroUI v3?
HeroUI-migration documents key breaking changes including the removal of the Provider requirement, renaming of event handlers (onClick becomes onPress), adoption of compound components for complex UI patterns, and styling adjustments for Tailwind v4 compatibility. Each change is explained with migration examples to help you understand the impact on your existing v2 code and how to adapt components accordingly.
Should I do a full or incremental migration to HeroUI v3?
HeroUI-migration helps you choose between full and incremental migration strategies. Full migration updates your entire application at once, ideal for smaller projects or when you want a clean break. Incremental migration updates components gradually, reducing risk and allowing parallel testing. The skill provides guidance for both approaches, including how to manage dependencies and maintain stability during the transition.
What styling and hooks need updating for HeroUI v3?
HeroUI-migration covers styling updates required for v3, including className/classNames changes and Tailwind v4 compatibility adjustments. For hooks, the skill provides migration documentation showing which hooks changed, were removed, or require new parameters. Component-specific examples demonstrate how to update your custom styling and hook usage to work with v3's new architecture.
Does HeroUI v3 still require a Provider wrapper?
HeroUI-migration clarifies that v3 removes the Provider requirement that was mandatory in v2. This simplifies setup and reduces boilerplate code. The skill explains how to remove Provider wrappers from your application structure and what configuration changes are needed to ensure your components function correctly without this wrapper in the v3 architecture.
How do I migrate HeroUI components from v2 to v3?
HeroUI-migration provides component-specific migration documentation and examples for each HeroUI component. It shows how compound components work in v3, demonstrates event handler renaming (onClick to onPress), and explains prop changes. The skill includes practical code examples for common components, helping you understand the exact changes needed for your application's component usage.
SKILL.md
rendered from the published skill — quoted content, verbatim
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 |
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 7 files
skills/heroui-migration/LICENSE.txt
skills/heroui-migration/SKILL.md
skills/heroui-migration/scripts/get_component_migration_guides.mjs
skills/heroui-migration/scripts/get_hooks_migration_guide.mjs
skills/heroui-migration/scripts/get_migration_guide.mjs
skills/heroui-migration/scripts/get_styling_migration_guide.mjs
skills/heroui-migration/scripts/list_migration_guides.mjs