docs(migration): write guide from v3 to v4 (#4802)

Co-authored-by: Benjamin Canac <[email protected]>

Author: HugoRCD

docs/content/docs/1.getting-started/3.migration/1.v4.md

@@ -9,4 +9,346 @@ links:
     icon: 'i-lucide-arrow-right-left'
 ---
 
+Nuxt UI v4 marks a major milestone: **Nuxt UI and Nuxt UI Pro are now unified into a single, fully open-source and free library**. You now have access to 100+ production-ready components, all available in the `@nuxt/ui` package.
+
+::note
+Nuxt UI v4 requires **Nuxt 4** due to some dependencies. Make sure to upgrade to Nuxt 4 before migrating to Nuxt UI v4.
+::
+
+This guide provides step-by-step instructions to migrate your application from v3 to v4.
+
 ## Migrate your project
+
+### From Nuxt UI Pro
+
+1. Replace `@nuxt/ui-pro` with `@nuxt/ui` in your `package.json`:
+
+::code-group{sync="pm"}
+
+```bash [pnpm]
+pnpm remove @nuxt/ui-pro
+pnpm add @nuxt/ui@alpha
+```
+
+```bash [yarn]
+yarn remove @nuxt/ui-pro
+yarn add @nuxt/ui@alpha
+```
+
+```bash [npm]
+npm uninstall @nuxt/ui-pro
+npm install @nuxt/ui@alpha
+```
+
+```bash [bun]
+bun remove @nuxt/ui-pro
+bun add @nuxt/ui@alpha
+```
+
+::
+
+::framework-only
+#nuxt
+:::div
+
+2. Replace `@nuxt/ui-pro` with `@nuxt/ui` in your `nuxt.config.ts`:
+
+```diff [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: [
+-   '@nuxt/ui-pro',
++   '@nuxt/ui'
+  ]
+})
+```
+:::
+
+#vue
+:::div
+
+2. Replace `@nuxt/ui-pro` with `@nuxt/ui` in your `vite.config.ts`:
+
+```diff [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'
+        }
+      }
+    })
+  ]
+})
+```
+:::
+::
+
+::framework-only
+#nuxt
+:::div
+3. Use the `ui` key instead of `uiPro` in your `app.config.ts`:
+
+```diff [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    colors: {
+      primary: 'green',
+      neutral: 'slate'
+    },
++   pageCard: {
++     slots: {
++       root: 'rounded-xl',
++     }
++   }
+  },
+- uiPro: {
+-   pageCard: {
+-     slots: {
+-       root: 'rounded-xl',
+-     }
+-   }
+- }
+})
+```
+:::
+
+#vue
+:::div
+3. Use the `ui` key instead of `uiPro` in your `vite.config.ts`:
+
+```diff [vite.config.ts]
+export default defineConfig({
+  plugins: [
+    vue(),
+    ui({
+      ui: {
+        colors: {
+          primary: 'green',
+          neutral: 'slate'
+        },
++       pageCard: {
++         slots: {
++           root: 'rounded-xl',
++         }
++       }
+      },
+-     uiPro: {
+-       pageCard: {
+-         slots: {
+-           root: 'rounded-xl',
+-         }
+-       }
+-     }
+    })
+  ]
+})
+```
+:::
+::
+
+4. Replace `@nuxt/ui-pro` with `@nuxt/ui` in your CSS:
+
+::framework-only
+#nuxt
+:::div
+```diff [app/assets/css/main.css]
+@import "tailwindcss";
+- @import "@nuxt/ui-pro";
++ @import "@nuxt/ui";
+```
+:::
+
+#vue
+:::div
+```diff [src/assets/css/main.css]
+@import "tailwindcss";
+- @import "@nuxt/ui-pro";
++ @import "@nuxt/ui";
+```
+:::
+::
+
+### From Nuxt UI
+
+1. When upgrading from Nuxt UI v3, you simply need to update to v4:
+
+::code-group{sync="pm"}
+
+```bash [pnpm]
+pnpm add @nuxt/ui@alpha
+```
+
+```bash [yarn]
+yarn add @nuxt/ui@alpha
+```
+
+```bash [npm]
+npm install @nuxt/ui@alpha
+```
+
+```bash [bun]
+bun add @nuxt/ui@alpha
+```
+
+::
+
+## Changes from v3
+
+After upgrading to Nuxt UI v4, please note the following important changes:
+
+### Merged components
+
+Nuxt UI Pro components have been integrated into the main `@nuxt/ui` package. You can keep using them as before, but you now need to import from `@nuxt/ui` instead of `@nuxt/ui-pro`:
+
+```diff
+- import type { BannerProps } from '@nuxt/ui-pro'
++ import type { BannerProps } from '@nuxt/ui'
+```
+
+### Renamed components
+
+Several components have been renamed for better consistency:
+
+1. `ButtonGroup` has been replaced with [`FieldGroup`](/docs/components/field-group):
+
+```diff
+<template>
+- <UButtonGroup>
++ <UFieldGroup>
+    <UButton label="Button" />
+    <UButton icon="i-lucide-chevron-down" />
+- </UButtonGroup>
++ </UFieldGroup>
+</template>
+```
+
+2. `PageMarquee` has been replaced with [`Marquee`](/docs/components/marquee):
+
+```diff
+<template>
+- <UPageMarquee :items="items" />
++ <UMarquee :items="items" />
+</template>
+```
+
+### Removed components
+
+Some components have been removed in favor of more standard alternatives:
+
+1. `PageAccordion` has been replaced with [`Accordion`](/docs/components/accordion):
+
+```diff
+<template>
+- <UPageAccordion :items="faqItems" />
++ <UAccordion :items="items" :unmount-on-hide="false" :ui="{ trigger: 'text-base', body: 'text-base text-muted' }" />
+</template>
+```
+
+### AI SDK v5 migration (optional)
+
+This section only applies if you're using the AI SDK and chat components (`ChatMessage`, `ChatMessages`, `ChatPrompt`, `ChatPromptSubmit`, `ChatPalette`). If you're not using AI features, you can skip this section.
+
+1. Update `@ai-sdk/vue` and `ai` dependencies in your `package.json`:
+
+```diff
+{
+  "dependencies": {
+-   "@ai-sdk/vue": "^1.2.x",
++   "@ai-sdk/vue": "^2.0.x",
+-   "ai": "^4.3.x"
++   "ai": "^5.0.x"
+  }
+}
+```
+
+2. `useChat` composable has been replaced with the new `Chat` class:
+
+```diff
+<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>
+```
+
+3. Messages now use `parts` instead of `content`:
+
+```diff
+// When manually creating messages
+- setMessages([{
++ messages.push({
+  id: '1',
+  role: 'user',
+- content: 'Hello world'
++ parts: [{ type: 'text', text: 'Hello world' }]
+- }])
++ })
+
+// In templates
+<template>
+- <UChatMessage :content="message.content" />
++ <UChatMessage :parts="message.parts" />
+</template>
+```
+
+4. Some methods have been renamed:
+
+```diff
+// Regenerate the last message
+- reload()
++ chat.regenerate()
+
+// Access chat state
+- :messages="messages"
+- :status="status"
++ :messages="chat.messages"
++ :status="chat.status"
+```
+
+5. New `getTextFromMessage` utility to extract text from AI SDK v5 message parts:
+
+```vue
+<script setup lang="ts">
+import { getTextFromMessage } from '@nuxt/ui/utils/ai'
+</script>
+
+<template>
+  <UChatMessages :messages="chat.messages" :status="chat.status">
+    <template #content="{ message }">
+      <!-- Extract text from message parts and render with MDC -->
+      <MDC :value="getTextFromMessage(message)" :cache-key="message.id" unwrap="p" />
+    </template>
+  </UChatMessages>
+</template>
+```
+
+::note{to="https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0" target="_blank"}
+For more details on AI SDK v5 changes, review the **official AI SDK v5 migration guide**.
+::
+
+::tip{to="https://github.com/nuxt/ui/pull/4698" target="_blank"}
+View all changes from AI SDK v4 to v5 **in the upgrade PR** for a detailed migration reference.
+::