PaperclipOrg
Claude Agent Skill · by Heroui Inc

Heroui Migration

Install Heroui Migration skill for Claude Code from heroui-inc/heroui.

Install
Terminal · npx
$npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices
Works with Paperclip

How Heroui Migration fits into a Paperclip company.

Heroui Migration drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md140 lines
Expand
---name: heroui-migrationdescription: "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 ```bashcurl -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 guidesnode scripts/list_migration_guides.mjs # Get main migration workflow (full or incremental)node scripts/get_migration_guide.mjs fullnode scripts/get_migration_guide.mjs incremental # Get component-specific migration guidesnode scripts/get_component_migration_guides.mjs buttonnode scripts/get_component_migration_guides.mjs button card modal # Get styling migration guidenode scripts/get_styling_migration_guide.mjs # Get hooks migration guidenode 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 changes2. **Compound components**: v3 uses `Card.Header`, `Card.Title`, `Button` with children—not flat props3. **No Provider**: Remove `HeroUIProvider` when migrating4. **onPress not onClick**: All interactive components use `onPress`5. **Workflow**: Analyze → Migrate components → Switch deps → Styling migration --- ## Migration Workflow Summary 1. Create migration branch2. 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 v36. Fetch styling guide: `node scripts/get_styling_migration_guide.mjs`7. 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.