mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 12:14:41 +01:00
docs(migration): add page
This commit is contained in:
Benjamin Canac
@@ -105,7 +105,7 @@ We want to be transparent: migrating from Nuxt UI v2 to v3 will require signific
|
||||
|
||||
Key points to consider:
|
||||
|
||||
- A comprehensive migration guide will be available in the coming weeks.
|
||||
- Read our [migration guide](/getting-started/migration) to upgrade your project from v2 to v3.
|
||||
- Review the new documentation and components carefully before attempting to upgrade.
|
||||
- If you encounter any issues, please report them on our [GitHub repository](https://github.com/nuxt/ui/issues).
|
||||
|
||||
|
||||
333
docs/content/1.getting-started/2.migration.md
Normal file
333
docs/content/1.getting-started/2.migration.md
Normal file
@@ -0,0 +1,333 @@
|
||||
---
|
||||
title: Migration
|
||||
description: 'A comprehensive guide to migrate your application from Nuxt UI v2 to Nuxt UI v3.'
|
||||
---
|
||||
|
||||
Nuxt UI v3.0 is a new major version rebuilt from the ground up, introducing a modern architecture with significant performance improvements and an enhanced developer experience. This major release includes several breaking changes alongside powerful new features and capabilities:
|
||||
|
||||
- **Tailwind CSS v4**: Migration from JavaScript to CSS-based configuration
|
||||
- **Reka UI**: Replacing Headless UI as the underlying component library
|
||||
- **Tailwind Variants**: New styling API for component variants
|
||||
|
||||
This guide provides step by step instructions to migrate your application from v2 to v3.
|
||||
|
||||
## Migrate your project
|
||||
|
||||
::steps
|
||||
|
||||
### Update Tailwind CSS
|
||||
|
||||
Tailwind CSS v4 introduces significant changes to its configuration approach. The official Tailwind upgrade tool will help automate most of the migration process.
|
||||
|
||||
::note{to="https://tailwindcss.com/docs/upgrade-guide#changes-from-v3" target="_blank"}
|
||||
For a detailed walkthrough of all changes, refer to the official **Tailwind CSS v4 upgrade guide**.
|
||||
::
|
||||
|
||||
1. Create a `main.css` file and import it in your `nuxt.config.ts` file:
|
||||
|
||||
::code-group
|
||||
|
||||
```css [app/assets/css/main.css]
|
||||
@import "tailwindcss" theme(static);
|
||||
```
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
css: ['~/assets/css/main.css']
|
||||
})
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
2. Run the Tailwind CSS upgrade tool:
|
||||
|
||||
```bash
|
||||
npx @tailwindcss/upgrade
|
||||
```
|
||||
|
||||
### Update Nuxt UI
|
||||
|
||||
3. Install the latest version of the package:
|
||||
|
||||
::module-only
|
||||
#ui
|
||||
:::div
|
||||
|
||||
::::code-group{sync="pm"}
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add @nuxt/ui@next
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add @nuxt/ui@next
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install @nuxt/ui@next
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add @nuxt/ui@next
|
||||
```
|
||||
|
||||
::::
|
||||
|
||||
:::
|
||||
|
||||
#ui-pro
|
||||
:::div
|
||||
|
||||
::::code-group{sync="pm"}
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm add @nuxt/ui-pro@next
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add @nuxt/ui-pro@next
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install @nuxt/ui-pro@next
|
||||
```
|
||||
|
||||
```bash [bun]
|
||||
bun add @nuxt/ui-pro@next
|
||||
```
|
||||
|
||||
::::
|
||||
|
||||
:::
|
||||
|
||||
::
|
||||
|
||||
4. Import it in your CSS:
|
||||
|
||||
::module-only
|
||||
#ui
|
||||
:::div
|
||||
|
||||
```css [app/assets/css/main.css]{2}
|
||||
@import "tailwindcss" theme(static);
|
||||
@import "@nuxt/ui";
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#ui-pro
|
||||
:::div
|
||||
|
||||
```css [app/assets/css/main.css]{2}
|
||||
@import "tailwindcss" theme(static);
|
||||
@import "@nuxt/ui-pro";
|
||||
```
|
||||
|
||||
:::
|
||||
::
|
||||
|
||||
::module-only
|
||||
#ui
|
||||
|
||||
:::div
|
||||
5. Wrap you app with the [App](/components/app) component:
|
||||
:::
|
||||
|
||||
#ui-pro
|
||||
:::div
|
||||
5. Add the `@nuxt/ui-pro` module in your `nuxt.config.ts` file as it's no longer a layer:
|
||||
|
||||
```diff [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
- extends: ['@nuxt/ui-pro'],
|
||||
- modules: ['@nuxt/ui']
|
||||
+ modules: ['@nuxt/ui-pro']
|
||||
})
|
||||
```
|
||||
|
||||
6. Wrap you app with the [App](/components/app) component:
|
||||
:::
|
||||
|
||||
::
|
||||
|
||||
```vue [app.vue] {2,4}
|
||||
<template>
|
||||
<UApp>
|
||||
<NuxtPage />
|
||||
</UApp>
|
||||
</template>
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
## Changes from v2
|
||||
|
||||
Now that you have updated your project, you can start migrating your code. Here's a comprehensive list of all the breaking changes in Nuxt UI v3.
|
||||
|
||||
### Updated design system
|
||||
|
||||
In Nuxt UI v2, we had a mix between a design system with `primary`, `gray`, `error` aliases and all the colors from Tailwind CSS. We've replaced it with a proper [design system](/getting-started/theme#design-system) with 7 color aliases:
|
||||
|
||||
| Color | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `primary`{color="primary"} | `green` | Main brand color, used as the default color for components. |
|
||||
| `secondary`{color="secondary"} | `blue` | Secondary color to complement the primary color. |
|
||||
| `success`{color="success"} | `green` | Used for success states. |
|
||||
| `info`{color="info"} | `blue` | Used for informational states. |
|
||||
| `warning`{color="warning"} | `yellow` | Used for warning states. |
|
||||
| `error`{color="error"} | `red` | Used for form error validation states. |
|
||||
| `neutral` | `slate` | Neutral color for backgrounds, text, etc. |
|
||||
|
||||
This change introduces several breaking changes that you need to be aware of:
|
||||
|
||||
1. The `gray` color has been renamed to `neutral`
|
||||
|
||||
```diff
|
||||
<template>
|
||||
- <p class="text-gray-500 dark:text-gray-400" />
|
||||
+ <p class="text-neutral-500 dark:text-neutral-400" />
|
||||
</template>
|
||||
```
|
||||
|
||||
::note
|
||||
You can also use the new [design tokens](/getting-started/theme#neutral-palette) to handle light and dark mode:
|
||||
|
||||
```diff
|
||||
<template>
|
||||
- <p class="text-gray-500 dark:text-gray-400" />
|
||||
+ <p class="text-(--ui-text-muted) dark:text-(--ui-text-muted)" />
|
||||
|
||||
- <p class="text-gray-900 dark:text-white" />
|
||||
+ <p class="text-(--ui-text-highlighted) dark:text-(--ui-text-highlighted)" />
|
||||
</template>
|
||||
```
|
||||
::
|
||||
|
||||
2. The `DEFAULT` shade that let you write `text-primary` no longer exists, you can use [color shades](/getting-started/theme#color-shades) instead:
|
||||
|
||||
```diff
|
||||
<template>
|
||||
- <p class="text-primary">Hello</p>
|
||||
+ <p class="text-(--ui-primary)">Hello</p>
|
||||
</template>
|
||||
```
|
||||
|
||||
3. The `gray`, `black` and `white` in the `color` props have been removed in favor of `neutral`:
|
||||
|
||||
```diff
|
||||
- <UButton color="black" />
|
||||
+ <UButton color="neutral" />
|
||||
|
||||
- <UButton color="gray" />
|
||||
+ <UButton color="neutral" variant="subtle" />
|
||||
|
||||
- <UButton color="white" />
|
||||
+ <UButton color="neutral" variant="outline" />
|
||||
```
|
||||
|
||||
4. You can no longer use Tailwind CSS colors in the `color` props, use the new aliases instead:
|
||||
|
||||
```diff
|
||||
- <UButton color="red" />
|
||||
+ <UButton color="error" />
|
||||
```
|
||||
|
||||
::note{to="/getting-started/theme#colors"}
|
||||
Learn how to extend the design system to add new color aliases.
|
||||
::
|
||||
|
||||
5. The color configuration in `app.config.ts` has been moved into a `colors` object:
|
||||
|
||||
```diff
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
- primary: 'green',
|
||||
- gray: 'cool'
|
||||
+ colors: {
|
||||
+ primary: 'green',
|
||||
+ neutral: 'slate'
|
||||
+ }
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Updated theming system
|
||||
|
||||
Nuxt UI components are now styled using the [Tailwind Variants API](/getting-started/theme#components-theme), which makes all the overrides you made using the `app.config.ts` and the `ui` prop obsolete.
|
||||
|
||||
1. Update your [`app.config.ts`](/getting-started/theme#config) to override components with their new theme:
|
||||
|
||||
```diff
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
button: {
|
||||
- font: 'font-bold',
|
||||
- default: {
|
||||
- size: 'md',
|
||||
- color: 'primary'
|
||||
- }
|
||||
+ slots: {
|
||||
+ base: 'font-medium'
|
||||
+ },
|
||||
+ defaultVariants: {
|
||||
+ size: 'md',
|
||||
+ color: 'primary'
|
||||
+ }
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
2. Update your [`ui` props](/getting-started/theme#props) to override each component's slots using their new theme:
|
||||
|
||||
```diff
|
||||
<template>
|
||||
- <UButton :ui="{ font: 'font-bold' }" />
|
||||
+ <UButton :ui="{ base: 'font-bold' }" />
|
||||
</template>
|
||||
```
|
||||
|
||||
::tip{to="/components/button#theme"}
|
||||
We can't detail all the changes here but you can check each component's theme in the **Theme** section.
|
||||
::
|
||||
|
||||
### Renamed components
|
||||
|
||||
We've renamed some components to align with the Reka UI naming convention.
|
||||
|
||||
| v2 | v3 |
|
||||
| --- | --- |
|
||||
| `Divider` | `Separator` |
|
||||
| `Dropdown` | `DropdownMenu` |
|
||||
| `FormGroup` | `FormField` |
|
||||
| `Range` | `Slider` |
|
||||
| `Toggle` | `Switch` |
|
||||
| `Notification` | `Toast` |
|
||||
| `VerticalNavigation` | `NavigationMenu` with `orientation="vertical"` |
|
||||
| `HorizontalNavigation` | `NavigationMenu` with `orientation="horizontal"` |
|
||||
|
||||
### Changed components
|
||||
|
||||
In addition to the renamed components, there are lots of changes to the components API. Let's detail the most important ones:
|
||||
|
||||
1. The `links` and `options` props have been renamed to `items` for consistency:
|
||||
|
||||
```diff
|
||||
<template>
|
||||
- <USelect :options="countries" />
|
||||
+ <USelect :items="countries" />
|
||||
|
||||
- <UHorizontalNavigation :links="links" />
|
||||
+ <UNavigationMenu :items="items" />
|
||||
</template>
|
||||
```
|
||||
|
||||
::note
|
||||
This change affects the following components: `Breadcrumb`, `HorizontalNavigation`, `InputMenu`, `RadioGroup`, `Select`, `SelectMenu`, `VerticalNavigation`.
|
||||
::
|
||||
|
||||
---
|
||||
|
||||
::warning
|
||||
This page is a work in progress, we'll improve it regularly.
|
||||
::
|
||||
Reference in New Issue
Block a user