fcakyon/claude-codex-settings / plugins/heroui-skills/skills/heroui-migration
heroui-migration
VerifiedHeroUI 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.
| File | Kind | Size |
|---|---|---|
| LICENSE.txt | markdown | 11.0 KB |
| SKILL.md | skill md | 4.6 KB |
| scripts/get_component_migration_guides.mjs | script | 2.8 KB |
| scripts/get_hooks_migration_guide.mjs | script | 1.2 KB |
| scripts/get_migration_guide.mjs | script | 1.6 KB |
| scripts/get_styling_migration_guide.mjs | script | 1.2 KB |
| scripts/list_migration_guides.mjs | script | 1.3 KB |
SKILL.md
View on GitHub---
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
```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): 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:
```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 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |