# Installation

Starwind configures an existing Astro or React 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 or React adapter, file locations,
and framework integration.

Starwind v3 is stable and published on npm's `latest` tag. The commands below install the
Runtime-backed Astro and React setup documented on this site.

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

## Choose Your Framework

The `starwind init` command will auto-detect and configure supported frameworks. Full guides can be found below.

<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>
<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>

## What Starwind Adds

- The framework adapter is `@starwind-ui/astro` or `@starwind-ui/react`. React hosts share the
public `react` adapter value in `starwind.config.json`.
- `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 framework guides explain the supported project shape and the manual integration points for
aliases, CSS entry files, Tailwind, and theme initialization. They reference the shared stylesheet
instead of repeating it. Start with [Theming](/docs/getting-started/theming/) when you need the full
token and stylesheet model.

## 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>
</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>
</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.