diff --git a/docs/content/1.getting-started/1.index.md b/docs/content/1.getting-started/1.index.md index 6fbdfd7f..66e0d68c 100644 --- a/docs/content/1.getting-started/1.index.md +++ b/docs/content/1.getting-started/1.index.md @@ -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). diff --git a/docs/content/1.getting-started/2.migration.md b/docs/content/1.getting-started/2.migration.md new file mode 100644 index 00000000..8ff8d16e --- /dev/null +++ b/docs/content/1.getting-started/2.migration.md @@ -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} + +``` + +:: + +## 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 + +``` + +::note +You can also use the new [design tokens](/getting-started/theme#neutral-palette) to handle light and dark mode: + +```diff + +``` +:: + +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 + +``` + +3. The `gray`, `black` and `white` in the `color` props have been removed in favor of `neutral`: + +```diff +- ++ + +- ++ + +- ++ +``` + +4. You can no longer use Tailwind CSS colors in the `color` props, use the new aliases instead: + +```diff +- ++ +``` + +::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 + +``` + +::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 + +``` + +::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. +::