# Installation

Starwind configures an existing Astro, React, or Vue framework project. Create the application with its
official starter first, then run Starwind from the project root.

## Quick Start

`init --defaults` examines the project before it selects the Astro, React, or Vue adapter, file locations,
and framework integration.

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

## Choose Your Framework

The CLI detects supported hosts. Choose a guide for the framework your components use.

### Astro

<div class="not-sw-prose my-6 grid grid-cols-1 items-stretch gap-4 md:grid-cols-2">
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/astro/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <AstroIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Astro</span>
</a>
</div>

### React

<div class="not-sw-prose my-6 grid grid-cols-1 items-stretch gap-4 md:grid-cols-2">
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/vite-react/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <ViteIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Vite React</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/nextjs/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <NextJsIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Next.js</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/tanstack-start/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <TanStackIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">TanStack Start</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/react-router/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <RouteIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">React Router</span>
</a>
</div>

### Vue (Beta)

Vue 3.5 support is in public beta. APIs can change during the `0.x` release series.
It includes Primitive adapters and editable Styled components. Styled Image is Astro-only.
Select the Vue tab on component examples; the API tables currently cover Astro and React.
Use the installed Vue prop types for model and event signatures. Report beta issues through the
[issue tracker](https://github.com/starwind-ui/starwind-ui/issues).

<div class="not-sw-prose my-6 grid grid-cols-1 items-stretch gap-4 md:grid-cols-2">
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/vite-vue/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <VueIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Vite Vue · Beta</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/astro/#vue-islands-beta">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <AstroIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Astro + Vue · Beta</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/nuxt/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <NuxtIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Nuxt 3 and 4 · Beta</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/laravel-inertia-vue/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <LaravelIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Laravel with Inertia Vue · Beta</span>
</a>
<a class="border-border bg-card hover:border-primary-accent/50 focus-visible:ring-primary-accent group m-0 flex h-full min-h-40 flex-col items-center justify-center gap-4 rounded-xl border p-5 text-center no-underline shadow-sm transition duration-200 focus-visible:ring-2 focus-visible:outline-none" href="/docs/frameworks/quasar/">
<span class="border-border bg-muted text-foreground group-hover:text-primary-accent flex size-11 items-center justify-center rounded-lg border transition-colors">
  <VueIcon class="size-6" aria-hidden="true" />
</span>
<span class="text-foreground group-hover:text-primary-accent text-base font-semibold transition-colors">Quasar Vite SPA / SSR · Beta</span>
</a>
</div>

## What Starwind Adds

- The framework adapter is `@starwind-ui/astro`, `@starwind-ui/react`, or `@starwind-ui/vue@beta`.
React hosts use `react` in `starwind.config.json`; Vue hosts use `vue`. Astro can also host
secondary React and Vue targets.
- `starwind.config.json` records the registry, adapter, stylesheet, component directory, utility
directory, and installed component versions.
- Styled components are copied into your application. You own their source and can edit it.
- The common Starwind stylesheet provides Tailwind CSS v4, design tokens, dark mode, animation
utilities, and shared component styles.

## Manual Setup

The [Manual Setup guide](/docs/getting-started/manual-setup/) covers the shared packages,
`starwind.config.json`, source paths, and complete base stylesheet. Finish with your framework guide
to connect aliases, CSS entry files, Tailwind, and theme initialization.

## Add a Component

After initialization, install `Button` from the styled registry.

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

## Render the Component

<DocsTabs syncKey="adapter" defaultValue="astro">
<DocsTabsList>
<DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
<DocsTabsTrigger value="react">React</DocsTabsTrigger>
<DocsTabsTrigger value="vue">Vue · Beta</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="astro">
```astro
---
import { Button } from "@/components/starwind/button";
---

<Button>Hello World</Button>
```
</DocsTabsContent>
<DocsTabsContent value="react">
```tsx
import { Button } from "@/components/starwind/button";

export function Example() {
  return <Button>Hello World</Button>;
}
```
</DocsTabsContent>
<DocsTabsContent value="vue">
```vue
<script setup lang="ts">
import { Button } from "@/components/starwind/button";
</script>

<template>
  <Button>Hello World</Button>
</template>
```
</DocsTabsContent>
</DocsTabs>

## Go Deeper

- [CLI](/docs/getting-started/cli/) documents detection, commands, and options.
- [Theming](/docs/getting-started/theming/) explains the common stylesheet and design tokens.
- [Dark Mode](/docs/getting-started/dark-mode/) explains theme initialization and controls.
- [Primitives](/docs/getting-started/primitives/) covers adapter packages and vendored Primitive
source.
- [Runtime And Raw HTML](/docs/runtime/) covers the framework-independent Runtime APIs.