# Nuxt Installation

> **Info:** Vue 3.5 support is in public beta. It includes Primitive adapters and editable Styled components.
APIs can change during the `0.x` release series. Report beta issues through the
[Starwind UI issue tracker](https://github.com/starwind-ui/starwind-ui/issues).

This guide covers Nuxt 3 and Nuxt 4 with Vue 3.5 or newer.

## Create a Nuxt Project

Use the [official Nuxt starter](https://nuxt.com/docs/4.x/getting-started/installation) for a new
Nuxt 4 app. Skip this step for an existing Nuxt 3 or 4 project.

```bash
npm create nuxt@latest my-app
```

Enter `my-app` and finish dependency installation with the package manager chosen in the starter.

## Requirements

The CLI expects a root `nuxt.config.ts` with a static `defineNuxtConfig({ ... })` export.
Nuxt 4 uses `app/app.vue`; Nuxt 3 uses a root `app.vue`. Keep the standard source directory.

## Initialize Starwind

```bash
npx starwind@latest init --framework vue --defaults
```

Starwind installs the Vue beta adapter, registers the stylesheet in Nuxt's `css` array, and adds
Tailwind to `vite.plugins`. The Nuxt component scan excludes Starwind's TypeScript helper files.
Use explicit imports from each component's `index.ts` as shown below.

## Add Button

```bash
npx starwind@latest add button
```

## Nuxt 4

| Purpose | Path |
| --- | --- |
| Styled components | `app/components/starwind` |
| Shared utilities | `app/lib/utils` |
| Starwind stylesheet | `app/assets/css/starwind.css` |

```vue title="app/app.vue"
<script setup lang="ts">
import { Button } from "~/components/starwind/button";
</script>

<template>
  <Button>Hello from Nuxt</Button>
</template>
```

## Nuxt 3

| Purpose | Path |
| --- | --- |
| Styled components | `components/starwind` |
| Shared utilities | `lib/utils` |
| Starwind stylesheet | `assets/css/starwind.css` |

```vue title="app.vue"
<script setup lang="ts">
import { Button } from "~/components/starwind/button";
</script>

<template>
  <Button>Hello from Nuxt</Button>
</template>
```

## Framework Wiring

Complete the [shared manual setup](/docs/getting-started/manual-setup/) with the Vue adapter and
the paths for your Nuxt version. Merge these entries into the existing config:

```ts title="nuxt.config.ts"
import tailwindcss from "@tailwindcss/vite";

export default defineNuxtConfig({
  css: ["~/assets/css/starwind.css"],
  components: [
    { path: "~/components", ignore: ["starwind/**/*.ts", "starwind-primitives/**/*.ts"] },
  ],
  vite: { plugins: [tailwindcss()] },
});
```

Nuxt owns the `~` and `@` source aliases. Follow
[Vue dark mode setup](/docs/getting-started/dark-mode/#vue-beta) for the theme initializer.

## Support Boundaries

Automatic setup covers the layouts above with Nuxt major 3 or 4 declared in `package.json`.
Custom `srcDir`, layers through `extends`, alternate builders, and dynamic config shapes require
manual setup. Keep browser-only work inside Vue mount hooks when adding application behavior.

## Next Steps

Select the Vue tab on component examples. See [Dialog](/docs/components/dialog/) for controlled
state and [Input](/docs/components/input/) for form binding. The Styled Image component is Astro-only.