Agent Migration Guide - Incremental Migration with Coexistence

Overview

This guide is designed for AI assistants (agents) helping users migrate from HeroUI v2 to v3 using incremental coexistence migration. This approach allows v2 and v3 components to work side-by-side, enabling component-by-component migration while keeping the project functional.

Key Principles

1. Incremental Component Migration: Migrate one component at a time, testing each before proceeding
2. Project Remains Functional: Unlike full migration, the project should remain working throughout
3. Strategy Identification: Determine which coexistence strategy the project uses (A: pnpm aliases or B: component packages)
4. Component-by-Component Testing: Test each migrated component before moving to the next
5. CSS Conflict Management: Monitor and resolve styling conflicts between v2 and v3 during coexistence
6. Removed Components: v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User) can be left in place during coexistence. Do not migrate them unless the user explicitly asks to replace them.

Major Changes in v3

Major Changes

• Dependencies: Update React to v19+, HeroUI packages to v3, Tailwind CSS to v4, remove Framer Motion
• No Provider Required: v3 removes the need for HeroUIProvider
• Component API Updates: Many components use React Aria Components patterns
• Compound Components: New compound component patterns for better customization. See individual component guides for details.
• Hooks Removed: v2 component hooks like useSwitch or useInput are removed - use compound components instead. useDisclosure is replaced with useOverlayState. See the Hooks Migration Guide for details.
• Configuration: Remove heroui() plugin from Tailwind config, update CSS imports, remove hero.ts file
• Item identity: Collection items (Dropdown, Listbox, Select, Accordion, etc.) now use id and textValue in v3; keep React's key for lists.

Incremental Migration Setup

For detailed setup and migration instructions, see the Incremental Migration Guide. The guide covers:

• Strategy selection (A: pnpm aliases or B: component packages)
• Detailed setup for each strategy
• CSS configuration for coexistence
• Component-by-component migration process
• CSS conflict handling
• Completing the migration

Strategy Identification

For projects using incremental coexistence strategies, agents should:

1. Identify the strategy: Check if project uses pnpm aliases (Strategy A) or component packages (Strategy B)

   • Strategy A: Look for aliases like "@heroui-v3/react": "npm:@heroui/react@latest" in package.json
   • Strategy B: Look for component-specific packages like @heroui/button, @heroui/card alongside @heroui/react

2. Verify setup: Ensure the coexistence setup is correct:

   • Strategy A: Both @heroui/react (v2) and @heroui-v3/react (v3 alias) are installed
   • Strategy B: @heroui/react (v3) and component packages like @heroui/button (v2) are installed
   • CSS is configured for both versions (see CSS Configuration section)

Component-by-Component Migration Guidance

For Strategy A (pnpm aliases):

1. Identify component to migrate

   • Review the component migration reference table
   • Use get_component_migration_guides MCP tool to fetch component-specific guide

2. Update imports

   • Change imports from @heroui/react to @heroui-v3/react
   • Example: import {Button} from "@heroui/react" → import {Button} from "@heroui-v3/react"

3. Update component code

   • Follow component migration guide from get_component_migration_guides tool
   • Update props, component structure, and API calls
   • Replace hooks with compound components if needed

4. Test the migrated component

   • Verify component renders correctly
   • Test functionality and interactions
   • Check for styling conflicts

5. Document migration

   • Track which components have been migrated
   • Note any issues or concerns

For Strategy B (component packages):

1. Identify component to migrate

   • Review the component migration reference table
   • Use get_component_migration_guides MCP tool to fetch component-specific guide

2. Remove component package

   • Remove the v2 component package from dependencies (e.g., @heroui/button)
   • Update package.json

3. Update imports

   • Change imports from component package to @heroui/react (v3)
   • Example: import {Card} from "@heroui/card" → import {Card} from "@heroui/react"

4. Update component code

   • Follow component migration guide from get_component_migration_guides tool
   • Update props, component structure, and API calls
   • Replace hooks with compound components if needed

5. Test the migrated component

   • Verify component renders correctly
   • Test functionality and interactions
   • Check for styling conflicts

6. Document migration

   • Track which components have been migrated
   • Note any issues or concerns

Handling Removed Components (No v3 Counterpart)

When encountering v2 components with no v3 counterpart (Code, Image, Navbar, Ripple, Snippet, Spacer, User):

• Leave them in place — do not attempt to migrate them unless the user explicitly requests removal
• If the user wants to remove them: Use get_component_migration_guides (where available) or the Component Migration Reference to fetch guides and help replace with native HTML or manual implementations

CSS Conflict Handling

During coexistence, both v2 and v3 CSS systems will be loaded. Agents should:

1. Monitor for conflicts

   • Watch for styling inconsistencies
   • Check if v2 and v3 styles are conflicting
   • Verify both CSS imports are present and in correct order

2. Guide conflict resolution

   • Ensure CSS import order: tailwindcss first, then @heroui/styles
   • Check Tailwind config has v2 plugin configured
   • Verify v3 CSS is imported correctly

3. Test styling after each migration

   • Verify migrated components look correct
   • Check for unexpected style overrides
   • Ensure v2 components still styled correctly

Component Migration Reference

Use the table below to quickly find migration guidance for each component. Use the link in the "Migration Guide" column to jump to detailed migration instructions.

Use the get_component_migration_guides MCP tool to fetch detailed guides for each component.

New Components in v3

New Components in v3

v3 introduces a number of new components not available in v2:

Component	Purpose	Documentation
TextField	Enhanced text input with label and description support	View docs →
TextArea	Multi-line text input component	View docs →
AlertDialog	Modal dialog for confirmations and alerts	View docs →
Label	Accessible form label component	View docs →
Description	Helper text for form fields	View docs →
FieldError	Form field error message display	View docs →
Fieldset	Group related form fields	View docs →
InputGroup	Compose multiple inputs together	View docs →
Surface	Container component with elevation styles	View docs →
Disclosure	Expandable/collapsible content sections	View docs →
DisclosureGroup	Compound component for multiple disclosure sections	View docs →
SearchField	Search input with clear button and optional loading state	View docs →
DateField	Date input with calendar picker	View docs →
TimeField	Time input component	View docs →
Tag, TagGroup	Tags and tag group for selection or display	View docs →
ColorPicker	Color selection (ColorArea, ColorField, ColorSlider, ColorSwatch, ColorSwatchPicker)	View docs →
CloseButton	Dismiss or close trigger button	View docs →
ErrorMessage	Form field error display (React Aria integration)	View docs →

Completion Steps

Once all components are migrated:

1. Remove v2 dependencies

   • Strategy A: Remove @heroui/react, @heroui/theme, and aliases
   • Strategy B: Remove all remaining @heroui/* component packages
   • If the project contains v2 removed components (Code, Image, Navbar, Ripple, Snippet, Spacer, User), inform the user they may ask to remove them later using the provided guides.

2. Update all imports

   • Strategy A: Change @heroui-v3/react → @heroui/react
   • Strategy B: All imports should already be @heroui/react (v3)

3. Update CSS configuration

   • Remove v2 Tailwind plugin from config
   • Keep only @import "@heroui/styles";
   • Remove v2 CSS imports

4. Complete styling migration

   • Follow the styling migration guide
   • Use get_styling_migration_guide MCP tool
   • Update utility classes, color tokens, etc.

Differences from Full Migration

Key Differences:

• Project State: Project remains functional during migration (no broken state)
• Migration Pace: Can migrate over extended period, component by component
• Testing: Can test v3 components alongside v2 before full migration
• Branch Strategy: Feature branch less critical (though still recommended)
• Dependency Management: Both versions coexist temporarily
• CSS Handling: Both CSS systems loaded during coexistence period

When to Use Incremental Coexistence:

• Large codebases that need gradual migration
• Projects that must remain functional during migration
• Teams that want to test v3 components incrementally
• Projects already using component-specific packages (Strategy B)

When to Use Full Migration:

• Smaller projects that can migrate quickly
• Projects where temporary broken state is acceptable
• Teams that prefer all-at-once migration
• Projects using unified @heroui/react package (Strategy A can work but full migration may be simpler)

Best Practices for Agents

1. Verify project remains functional

   • After each component migration, ensure project still works
   • Test both migrated and non-migrated components
   • Report any issues immediately

2. Guide component-by-component migration

   • Help migrate one component at a time
   • Use get_component_migration_guides MCP tool for each component
   • Test thoroughly before proceeding

3. Monitor CSS conflicts

   • Watch for styling issues between v2 and v3
   • Guide resolution of conflicts
   • Ensure CSS configuration is correct

4. Track migration progress

   • Keep a checklist of migrated components
   • Document any issues or concerns
   • Note which strategy is being used

5. Guide completion steps

   • Once all components migrated, guide removal of v2 dependencies
   • Help update all imports to v3-only
   • Guide styling migration completion

Common Scenarios

Large Project (100+ components)

• Migrate components incrementally over time
• Test each component thoroughly
• Monitor for CSS conflicts
• Can take weeks or months to complete

Small Project (<20 components)

• Can migrate more quickly
• Still test each component
• Less CSS conflict risk
• May complete in days

Mixed Strategy Projects

• Some projects may use Strategy A for some components, Strategy B for others
• Guide appropriate import updates for each component
• Ensure consistent approach where possible

Project Uses v2 Navbar (or Other Removed Components)

• Leave in place — v2 Navbar and other removed components (Code, Image, Ripple, Snippet, Spacer, User) will continue to work during coexistence
• Inform the user they can optionally remove them later with agent assistance and the Component Migration Reference guides

Next Steps

After completing migration:

1. Remove v2 dependencies (already done in completion steps)
2. Switch from Migration MCP to heroui-react MCP for v3 development
3. Update documentation references
4. Run final verification
5. Complete styling migration

---