Nuxt UI Migration Command

Migrate from Nuxt UI v2/v3 to v4 with automated breaking change fixes.

Arguments

• --dry-run: Show changes without applying them
• --from v3: Specify source version (default: auto-detect)

Instructions

1. Detect Current Version Read package.json to find current @nuxt/ui version.

2. Scan for Breaking Changes Search codebase for patterns that need updating:

   v3 Pattern	v4 Pattern	Files to Check
   <UButtonGroup>	<UFieldGroup>	*.vue
   <UPageMarquee>	<UMarquee>	*.vue
   <UPageAccordion>	<UAccordion>	*.vue
   v-model.nullify	v-model.nullable	*.vue
   .$el.focus()	.focus()	*.vue, *.ts
   useToast.js'	useToast'	*.ts, *.vue

3. Check Configuration Files

   • nuxt.config.ts - Module registration
   • app.vue - UApp wrapper, CSS imports
   • app.config.ts - Theme configuration
   • tailwind.config.* - Should be removed (v4 uses CSS)

4. Report Findings If --dry-run:

   • List all files with breaking changes
   • Show before/after for each change
   • Summarize total changes needed

5. Apply Fixes If not --dry-run:

   • Apply each fix with Edit tool
   • Track successful/failed changes
   • Report results

6. Update Dependencies

   bun update @nuxt/ui
   bun add tailwindcss@4
   

7. Post-Migration Checks

   bunx nuxt prepare
   bun run build
   

8. Highlight New Features After migration, inform about new v4 capabilities:

   • Dashboard components
   • Chat/AI components
   • Editor components
   • Page layout components
   • 125+ total components

Breaking Changes Reference

Component Renames

- <UButtonGroup>
+ <UFieldGroup>

- <UPageMarquee>
+ <UMarquee>

Removed Components

- <UPageAccordion>
+ <UAccordion unmount-on-hide="false">

Model Modifiers

- v-model.nullify="value"
+ v-model.nullable="value"

Template Refs (v4.2+)

- inputRef.value.$el.focus()
+ inputRef.value?.focus()

Composable Imports

- import { useToast } from '#ui/composables/useToast.js'
+ import { useToast } from '#ui/composables/useToast'

CSS Import Order

<style>
@import "tailwindcss";  /* FIRST */
@import "@nuxt/ui";     /* SECOND */
</style>

Form Changes

• Transformations now apply only to submit data
• Nested forms require explicit nested prop

Output

Summary report including:

• Files modified
• Changes applied
• Errors encountered
• Manual changes required
• New features available