Migrate your Nuxt application from Nuxt UI v3 or Nuxt UI Pro to Nuxt UI v4
Analyzes your project to prepare for migrating from Nuxt UI v3/Pro to v4. Checks dependencies, configuration, and AI SDK usage, then presents a summary for your approval before starting the migration.
/plugin marketplace add pleaseai/nuxt-ui/plugin install nuxt-ui@pleaseaicommands/You are assisting with migrating a Nuxt application to Nuxt UI v4. Nuxt UI v4 marks a major milestone where Nuxt UI and Nuxt UI Pro are now unified into a single, fully open-source and free library with 100+ production-ready components.
IMPORTANT: Nuxt UI v4 requires Nuxt 4. Ensure the project is on Nuxt 4 before proceeding.
First, analyze the current project setup:
Check if the project uses Nuxt UI Pro or Nuxt UI v3:
package.json to detect @nuxt/ui-pro or @nuxt/ui dependenciesnuxt.config.ts (or vite.config.ts for Vue projects) to confirm module configurationapp.config.ts (or vite.config.ts for Vue) for uiPro configurationVerify git status and ask the user:
feat/migrate-nuxt-ui-v4Check for AI SDK usage (optional migration):
@ai-sdk/vue or ai packagesChatMessage, ChatMessages, ChatPrompt, etc.Present a summary to the user:
**Migration Assessment**
- Current version: [Nuxt UI Pro / Nuxt UI v3]
- Nuxt version: [version]
- Framework: [Nuxt / Vue]
- AI SDK components detected: [Yes/No]
- Recommended branch: [branch-name]
Ready to proceed?
Wait for user approval before continuing.
Based on the detected setup, perform the appropriate dependency updates:
Remove @nuxt/ui-pro and install @nuxt/ui:
# Detect package manager (npm, pnpm, yarn, bun)
bun remove @nuxt/ui-pro
bun add @nuxt/ui
Update module configuration:
For Nuxt projects: Update nuxt.config.ts
export default defineNuxtConfig({
modules: [
- '@nuxt/ui-pro',
+ '@nuxt/ui'
]
})
For Vue projects: Update vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
- import uiPro from '@nuxt/ui-pro/vite'
+ import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
- uiPro({
+ ui({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
}
}
})
]
})
Update to latest version:
bun add @nuxt/ui
No module configuration changes needed (already using @nuxt/ui)
After dependency updates:
bun install to ensure clean installgit commit -m "chore: update to Nuxt UI v4 dependencies"Wait for user approval before continuing to Phase 2.
For Nuxt projects: Update app.config.ts
export default defineAppConfig({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
},
+ pageCard: {
+ slots: {
+ root: 'rounded-xl',
+ }
+ }
},
- uiPro: {
- pageCard: {
- slots: {
- root: 'rounded-xl',
- }
- }
- }
})
For Vue projects: Update vite.config.ts (move uiPro config to ui)
export default defineConfig({
plugins: [
vue(),
ui({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
},
+ pageCard: {
+ slots: {
+ root: 'rounded-xl',
+ }
+ }
},
- uiPro: {
- pageCard: {
- slots: {
- root: 'rounded-xl',
- }
- }
- }
})
]
})
Find CSS files (commonly app/assets/css/main.css or src/assets/css/main.css) and update:
@import "tailwindcss";
- @import "@nuxt/ui-pro";
+ @import "@nuxt/ui";
For Nuxt 4 projects upgrading simultaneously: Update @source directive if present:
@import "tailwindcss";
@import "@nuxt/ui";
- @source "../../content/**/*";
+ @source "../../../content/**/*";
After configuration updates:
npx nuxi typecheck (or npx vue-tsc for Vue) to check for issuesgit commit -m "chore: migrate configuration to Nuxt UI v4"Wait for user approval before continuing to Phase 3.
This phase updates component usage and imports throughout the codebase.
Search and replace the following component renames:
ButtonGroup → FieldGroup:
# Search for UButtonGroup usage
Replace with:
- <UButtonGroup>
+ <UFieldGroup>
<UButton label="Button" />
<UButton icon="i-lucide-chevron-down" />
+ </UFieldGroup>
- </UButtonGroup>
PageMarquee → Marquee:
- <UPageMarquee :items="items" />
+ <UMarquee :items="items" />
PageAccordion → Accordion (with additional props):
- <UPageAccordion
+ <UAccordion
:items="items"
+ :unmount-on-hide="false"
+ :ui="{ trigger: 'text-base', body: 'text-base text-muted' }"
/>
Search for v-model.nullify usage and update:
- <UInput v-model.nullify="value" />
+ <UInput v-model.nullable="value" />
- <UTextarea v-model="value" :model-modifiers="{ nullify: true }" />
+ <UTextarea v-model="value" :model-modifiers="{ nullable: true }" />
Note: Use nullable for null values, optional for undefined values.
Search for nested UForm components and update:
<template>
<UForm :state="state" :schema="schema" @submit="onSubmit">
<UFormField label="Customer" name="customer">
<UInput v-model="state.customer" placeholder="Wonka Industries" />
</UFormField>
<div v-for="(item, index) in state.items" :key="index">
<UForm
- :state="item"
+ :name="`items.${index}`"
:schema="itemSchema"
+ nested
>
<UFormField :label="!index ? 'Description' : undefined" name="description">
<UInput v-model="item.description" />
</UFormField>
</UForm>
</div>
</UForm>
</template>
Key changes:
nested prop to nested forms:state with :name for path-based state access@submit dataSearch for all imports from @nuxt/ui-pro and update:
- import type { BannerProps } from '@nuxt/ui-pro'
+ import type { BannerProps } from '@nuxt/ui'
- import { findPageHeadline } from '@nuxt/ui-pro/utils/content'
+ import { findPageHeadline } from '@nuxt/content/utils'
- import { findPageBreadcrumb } from '@nuxt/ui-pro/utils/content'
+ import { findPageBreadcrumb } from '@nuxt/content/utils'
After code migrations:
npx nuxi typecheck to verify no type errorsnpm run build to test buildgit commit -m "refactor: migrate components and imports to Nuxt UI v4"Wait for user approval before continuing to Phase 4 (if AI SDK detected).
Only perform this phase if AI SDK usage was detected in Phase 0.
Ask user: "AI SDK components were detected. Would you like to migrate to AI SDK v5? (Yes/No)"
If Yes:
{
"dependencies": {
- "@ai-sdk/vue": "^1.2.x",
+ "@ai-sdk/vue": "^2.0.x",
- "ai": "^4.3.x"
+ "ai": "^5.0.x"
}
}
Replace useChat with new Chat class:
<script setup lang="ts">
- import { useChat } from '@ai-sdk/vue'
+ import { Chat } from '@ai-sdk/vue'
+ import type { UIMessage } from 'ai'
- const { messages, input, handleSubmit, status, error, reload, setMessages } = useChat()
+ const messages: UIMessage[] = []
+ const input = ref('')
+
+ const chat = new Chat({
+ messages
+ })
+
+ function handleSubmit(e: Event) {
+ e.preventDefault()
+ chat.sendMessage({ text: input.value })
+ input.value = ''
+ }
</script>
Messages now use parts instead of content:
// When manually creating messages
- setMessages([{
+ messages.push({
id: '1',
role: 'user',
- content: 'Hello world'
+ parts: [{ type: 'text', text: 'Hello world' }]
- }])
+ })
// In templates
- <UChatMessage :content="message.content" />
+ <UChatMessage :parts="message.parts" />
// Regenerate the last message
- reload()
+ chat.regenerate()
// Access chat state
- :messages="messages"
- :status="status"
+ :messages="chat.messages"
+ :status="chat.status"
For MDC rendering with AI SDK v5:
<script setup lang="ts">
import { getTextFromMessage } from '@nuxt/ui/utils/ai'
</script>
<template>
<UChatMessages :messages="chat.messages" :status="chat.status">
<template #content="{ message }">
<MDC :value="getTextFromMessage(message)" :cache-key="message.id" unwrap="p" />
</template>
</UChatMessages>
</template>
After AI SDK migration:
npx nuxi typecheck to verify no type errorsgit commit -m "feat: migrate to AI SDK v5"Perform comprehensive checks:
Type checking:
npx nuxi typecheck # For Nuxt
npx vue-tsc # For Vue
Build verification:
npm run build
Run tests (if available):
npm run test
Lint check (if configured):
npm run lint
Development server:
npm run dev
Ask user to verify the application runs correctly.
Present a complete migration summary:
✅ Nuxt UI v4 Migration Complete
**Changes Applied:**
- ✅ Dependencies updated to @nuxt/ui v4
- ✅ Configuration migrated (nuxt.config.ts/vite.config.ts, app.config.ts)
- ✅ CSS imports updated
- ✅ Components renamed (ButtonGroup→FieldGroup, PageMarquee→Marquee, PageAccordion→Accordion)
- ✅ Model modifiers updated (nullify→nullable)
- ✅ Form components updated with nested prop
- ✅ Imports updated from @nuxt/ui-pro to @nuxt/ui
- [✅/➖] AI SDK v5 migration completed (if applicable)
**Verification Results:**
- Type checking: [✅/❌]
- Build: [✅/❌]
- Tests: [✅/❌]
- Lint: [✅/❌]
**Next Steps:**
1. Review the changes in git diff
2. Test your application thoroughly
3. Update any custom components that depend on changed APIs
4. Refer to the migration guide for additional edge cases: https://ui.nuxt.com/docs/getting-started/migration/v4
**References:**
- Nuxt UI v4 Migration Guide: https://ui.nuxt.com/docs/getting-started/migration/v4
- AI SDK v5 Migration Guide: https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0
- Nuxt UI v4 Upgrade PR: https://github.com/nuxt/ui/pull/4698
Ask the user if they want to:
Throughout the migration, if any step fails: