On this page

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.

pnpx starwind@latest init

npx starwind@latest init

yarn dlx starwind@latest init

For non-interactive initialization and every available option, see the CLI reference.

Manual Setup

Manual setup reproduces the project configuration performed by starwind init. Complete these steps for your framework, then continue to Add a Component.

1. Install dependencies

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

pnpm add @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

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

yarn add @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

pnpm add @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

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

yarn add @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

2. Configure the TypeScript alias

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

Add the alias to tsconfig.json.

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Add the alias to tsconfig.app.json when it exists; otherwise use tsconfig.json.

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. Configure Vite

Add the Tailwind Vite plugin to the Astro configuration.

import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "astro/config";

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

Add the Tailwind plugin, the @ alias, and Starwind’s pre-render theme initializer.

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()],
});

4. Create the Starwind configuration

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

{
  "$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": []
}

{
  "$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": []
}

5. Create the stylesheet

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

Show the complete Starwind stylesheet

@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;
  }
}

6. Import the stylesheet

Import the stylesheet in the shared Astro layout.

---
import "@/styles/starwind.css";
---

Import the stylesheet in the React entry file.

import "./styles/starwind.css";

Add a Component

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

pnpx starwind@latest add button

npx starwind@latest add button

yarn dlx starwind@latest add button

Render the Component

---
import { Button } from "@/components/starwind/button";
---

<Button>Hello World</Button>

import { Button } from "@/components/starwind/button";

export function Example() {
  return <Button>Hello World</Button>;
}

Go Deeper

Primitives explains package imports, vendored Primitive source, framework targeting, and ownership tradeoffs.
Runtime And Raw HTML covers direct Runtime APIs and framework-independent markup.
Theming covers tokens, Tailwind integration, and visual customization.
CLI is the complete command and option reference.