# Manual Setup

Use this guide when you want to create the files that `starwind init` normally manages. Complete
the shared setup here, then follow your framework guide for aliases, CSS imports, Tailwind wiring,
and theme initialization.

## Install the Shared Packages

Choose the adapter for the component source that you will add to the project. Astro components use
`@starwind-ui/astro`. Every supported React host uses `@starwind-ui/react`.

</DocsTabsContent>
<DocsTabs defaultValue="astro" syncKey="adapter">
  <DocsTabsList>
    <DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
    <DocsTabsTrigger value="react">React</DocsTabsTrigger>
  </DocsTabsList>
  <DocsTabsContent value="astro">
```bash
npm install @starwind-ui/astro @tabler/icons @tailwindcss/forms @tailwindcss/vite tailwind-merge tailwind-variants tailwindcss tw-animate-css
```
</DocsTabsContent>
<DocsTabsContent value="yarn">
<DocsTabs defaultValue="astro" syncKey="adapter">
  <DocsTabsList>
    <DocsTabsTrigger value="astro">Astro</DocsTabsTrigger>
    <DocsTabsTrigger value="react">React</DocsTabsTrigger>
  </DocsTabsList>
  <DocsTabsContent value="astro">
```bash
yarn add @starwind-ui/astro @tabler/icons @tailwindcss/forms @tailwindcss/vite tailwind-merge tailwind-variants tailwindcss tw-animate-css
```
  </DocsTabsContent>
  <DocsTabsContent value="react">
```bash
yarn add @starwind-ui/react @tabler/icons-react @tailwindcss/forms @tailwindcss/vite tailwind-merge tailwind-variants tailwindcss tw-animate-css
```
  </DocsTabsContent>
</DocsTabs>
</DocsTabsContent>
</DocsTabs>

The adapter package installs the matching Starwind Runtime dependency. Your framework starter
continues to own Astro, React, and other host packages.

## Create the Project Configuration

Create `starwind.config.json` in the project root. Select the tab that matches the generated
component source.

<DocsTabs defaultValue="astro" syncKey="adapter">
<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.2.0"
  },
  "components": [],
  "tailwind": {
    "css": "src/styles/starwind.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "componentDir": "src/components/starwind",
  "utilsDir": "src/lib/utils"
}
```
</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.2.0"
  },
  "components": [],
  "tailwind": {
    "css": "src/styles/starwind.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "componentDir": "src/components/starwind",
  "utilsDir": "src/lib/utils"
}
```
</DocsTabsContent>
</DocsTabs>

The CLI adds entries to `components` and `primitives` when you install source. Keep those arrays
under CLI control so `starwind update` can compare the installed versions with the registry.

## Create the Shared Stylesheet

Create `src/styles/starwind.css` with the Starwind foundation below. It loads Tailwind CSS v4,
animation utilities, form styles, semantic color tokens, radii, dark mode, and Sidebar tokens.

<details>
<summary>Show the complete 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-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);

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

The [Theming guide](/docs/getting-started/theming/) explains how to change the tokens after the base
stylesheet works in your application.

## Wire the Framework

Complete the host-specific setup for your project:

- [Astro](/docs/frameworks/astro/#framework-wiring)
- [Vite React](/docs/frameworks/vite-react/#framework-wiring)
- [Next.js](/docs/frameworks/nextjs/#app-router)
- [TanStack Start](/docs/frameworks/tanstack-start/#framework-wiring)
- [React Router](/docs/frameworks/react-router/#framework-wiring)

These sections configure aliases, stylesheet imports, Tailwind, and the prepaint theme script. They
also document host-specific source paths when a project does not use `src/`.

## Add a Component

After the shared and framework setup is complete, use the CLI to install component source and keep
the config version records current.

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