# Initial Setup

The recommended setup uses the Starwind CLI. If you prefer to configure the project yourself, the
manual path below replaces `starwind init`; the CLI remains the supported way to install copied
styled component source.

## Requirements

- Tailwind CSS v4.
- Astro 5 or newer, or a React project built with Vite.
- A project root containing the framework configuration and TypeScript configuration you want
Starwind to update or use.

## CLI Setup (Recommended)

Run initialization from your project root. The interactive flow asks for the framework, component
directory, stylesheet location, and Tailwind base color. It then installs the matching Starwind
adapter, creates the v2 configuration and stylesheet, configures path aliases, and wires the
stylesheet into the application.

```bash
npx starwind@latest init
```

For non-interactive initialization and every available option, see the
[CLI reference](/docs/getting-started/cli/#init).

## Manual Setup

Manual setup reproduces the project configuration performed by `starwind init`. Complete these
steps for your framework, then continue to [Add a Component](#add-a-component).

### 1. Install dependencies

Install the adapter for your framework together with Starwind's shared Tailwind dependencies.

```bash
npm install @starwind-ui/astro tailwindcss@^4 @tailwindcss/vite@^4 @tailwindcss/forms@^0.5 tw-animate-css@^1 tailwind-variants@^3 tailwind-merge@^3 @tabler/icons@^3
```
</DocsTabsContent>
```bash
npm install @starwind-ui/react tailwindcss@^4 @tailwindcss/vite@^4 @tailwindcss/forms@^0.5 tw-animate-css@^1 tailwind-variants@^3 tailwind-merge@^3 @tabler/icons@^3
```
</DocsTabsContent>
</DocsTabs>

### 2. Configure the TypeScript alias

Starwind's copied source imports project files through `@/*`.

<DocsTabs syncKey="framework" defaultValue="astro">
<DocsTabsList>
<DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
<DocsTabsTrigger value="react">React</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="astro">
Add the alias to `tsconfig.json`.

```json title="tsconfig.json"
{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```
</DocsTabsContent>
<DocsTabsContent value="react">
Add the alias to `tsconfig.app.json` when it exists; otherwise use `tsconfig.json`.

```json title="tsconfig.app.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```
</DocsTabsContent>
</DocsTabs>

### 3. Configure Vite

<DocsTabs syncKey="framework" defaultValue="astro">
<DocsTabsList>
<DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
<DocsTabsTrigger value="react">React</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="astro">
Add the Tailwind Vite plugin to the Astro configuration.

```js title="astro.config.mjs"
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "astro/config";

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});
```
</DocsTabsContent>
<DocsTabsContent value="react">
Add the Tailwind plugin, the `@` alias, and Starwind's pre-render theme initializer.

```ts title="vite.config.ts"
import { fileURLToPath } from "node:url";

import { getThemeInitScript } from "@starwind-ui/react/theme";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

function starwindThemeInitPlugin() {
  return {
    name: "starwind-theme-init",
    transformIndexHtml() {
      return [
        {
          tag: "script",
          attrs: { "data-starwind-theme-init": "" },
          children: getThemeInitScript(),
          injectTo: "head-prepend",
        },
      ];
    },
  };
}

export default defineConfig({
  resolve: {
    alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
  },
  plugins: [starwindThemeInitPlugin(), tailwindcss(), react()],
});
```
</DocsTabsContent>
</DocsTabs>

### 4. Create the Starwind configuration

Create `starwind.config.json` in the project root. Choose the framework value that matches your
project.

<DocsTabs syncKey="framework" defaultValue="astro">
<DocsTabsList>
<DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
<DocsTabsTrigger value="react">React</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="astro">
```json title="starwind.config.json"
{
  "$schema": "https://starwind.dev/config-schema.v2.json",
  "version": 2,
  "framework": "astro",
  "registry": { "source": "bundled", "version": "2.0.0" },
  "tailwind": {
    "css": "src/styles/starwind.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "componentDir": "src/components/starwind",
  "utilsDir": "src/lib/utils",
  "components": []
}
```
</DocsTabsContent>
<DocsTabsContent value="react">
```json title="starwind.config.json"
{
  "$schema": "https://starwind.dev/config-schema.v2.json",
  "version": 2,
  "framework": "react",
  "registry": { "source": "bundled", "version": "2.0.0" },
  "tailwind": {
    "css": "src/styles/starwind.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "componentDir": "src/components/starwind",
  "utilsDir": "src/lib/utils",
  "components": []
}
```
</DocsTabsContent>
</DocsTabs>

### 5. Create the stylesheet

Create the configured stylesheet at `src/styles/starwind.css`.

<details>
<summary>Show the complete Starwind stylesheet</summary>

```css title="src/styles/starwind.css"
@import "tailwindcss";
@import "tw-animate-css";
@plugin "@tailwindcss/forms";
@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --animate-accordion-down: accordion-down 0.2s ease-out;
  --animate-accordion-up: accordion-up 0.2s ease-out;

  @keyframes accordion-down {
    from {
      height: 0;
    }
    to {
      height: var(--starwind-accordion-content-height);
    }
  }

  @keyframes accordion-up {
    from {
      height: var(--starwind-accordion-content-height);
    }
    to {
      height: 0;
    }
  }
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-primary-accent: var(--primary-accent);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-secondary-accent: var(--secondary-accent);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
  --color-error: var(--error);
  --color-error-foreground: var(--error-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-outline: var(--outline);

  --radius-xs: calc(var(--radius) - 0.375rem);
  --radius-sm: calc(var(--radius) - 0.25rem);
  --radius-md: calc(var(--radius) - 0.125rem);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 0.25rem);
  --radius-2xl: calc(var(--radius) + 0.5rem);
  --radius-3xl: calc(var(--radius) + 1rem);

  --color-sidebar: var(--sidebar-background);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-outline: var(--sidebar-outline);
}

:root {
  --background: var(--color-white);
  --foreground: var(--color-neutral-950);
  --card: var(--color-white);
  --card-foreground: var(--color-neutral-950);
  --popover: var(--color-white);
  --popover-foreground: var(--color-neutral-950);
  --primary: var(--color-blue-700);
  --primary-foreground: var(--color-neutral-50);
  --primary-accent: var(--color-blue-700);
  --secondary: var(--color-neutral-200);
  --secondary-foreground: var(--color-neutral-950);
  --secondary-accent: var(--color-neutral-950);
  --muted: var(--color-neutral-100);
  --muted-foreground: var(--color-neutral-600);
  --accent: var(--color-neutral-100);
  --accent-foreground: var(--color-neutral-900);
  --info: var(--color-sky-300);
  --info-foreground: var(--color-sky-950);
  --success: var(--color-green-300);
  --success-foreground: var(--color-green-950);
  --warning: var(--color-amber-300);
  --warning-foreground: var(--color-amber-950);
  --error: var(--color-red-700);
  --error-foreground: var(--color-neutral-50);
  --border: var(--color-neutral-200);
  --input: var(--color-neutral-200);
  --outline: var(--color-neutral-400);
  --radius: 0.625rem;

  /* sidebar variables */
  --sidebar-background: var(--color-neutral-50);
  --sidebar-foreground: var(--color-neutral-950);
  --sidebar-primary: var(--color-blue-700);
  --sidebar-primary-foreground: var(--color-neutral-50);
  --sidebar-accent: var(--color-neutral-100);
  --sidebar-accent-foreground: var(--color-neutral-900);
  --sidebar-border: var(--color-neutral-200);
  --sidebar-outline: var(--color-neutral-400);
}

.dark {
  --background: var(--color-neutral-950);
  --foreground: var(--color-neutral-50);
  --card: var(--color-neutral-900);
  --card-foreground: var(--color-neutral-50);
  --popover: var(--color-neutral-900);
  --popover-foreground: var(--color-neutral-50);
  --primary: var(--color-blue-700);
  --primary-foreground: var(--color-neutral-50);
  --primary-accent: var(--color-blue-400);
  --secondary: var(--color-neutral-800);
  --secondary-foreground: var(--color-neutral-50);
  --secondary-accent: var(--color-neutral-50);
  --muted: var(--color-neutral-800);
  --muted-foreground: var(--color-neutral-400);
  --accent: var(--color-neutral-700);
  --accent-foreground: var(--color-neutral-50);
  --info: var(--color-sky-300);
  --info-foreground: var(--color-sky-950);
  --success: var(--color-green-300);
  --success-foreground: var(--color-green-950);
  --warning: var(--color-amber-300);
  --warning-foreground: var(--color-amber-950);
  --error: var(--color-red-800);
  --error-foreground: var(--color-neutral-50);
  --border: --alpha(var(--color-neutral-50) / 10%);
  --input: --alpha(var(--color-neutral-50) / 15%);
  --outline: var(--color-neutral-500);

  /* sidebars variables */
  --sidebar-background: var(--color-neutral-900);
  --sidebar-foreground: var(--color-neutral-50);
  --sidebar-primary: var(--color-blue-700);
  --sidebar-primary-foreground: var(--color-neutral-50);
  --sidebar-accent: var(--color-neutral-800);
  --sidebar-accent-foreground: var(--color-neutral-100);
  --sidebar-border: var(--color-neutral-800);
  --sidebar-outline: var(--color-neutral-600);
}

@layer base {
  * {
    @apply border-border outline-outline/50;
  }
  body {
    @apply bg-background text-foreground scheme-light dark:scheme-dark;
  }
  button {
    @apply cursor-pointer;
  }
}
```

</details>

### 6. Import the stylesheet

<DocsTabs syncKey="framework" defaultValue="astro">
<DocsTabsList>
<DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
<DocsTabsTrigger value="react">React</DocsTabsTrigger>
</DocsTabsList>
<DocsTabsContent value="astro">
Import the stylesheet in the shared Astro layout.

```astro title="src/layouts/Layout.astro"
---
import "@/styles/starwind.css";
---
```
</DocsTabsContent>
<DocsTabsContent value="react">
Import the stylesheet in the React entry file.

```tsx title="src/main.tsx"
import "./styles/starwind.css";
```
</DocsTabsContent>
</DocsTabs>

## Add a Component

Both setup paths now converge. Install `Button` from the styled registry:

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

## Render the Component

<DocsTabs syncKey="framework" 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

- [Primitives](/docs/getting-started/primitives/) explains package imports, vendored Primitive
source, framework targeting, and ownership tradeoffs.
- [Runtime And Raw HTML](/docs/runtime/) covers direct Runtime APIs and framework-independent
markup.
- [Theming](/docs/getting-started/theming/) covers tokens, Tailwind integration, and visual
customization.
- [CLI](/docs/getting-started/cli/) is the complete command and option reference.