On this page

Astro Installation

This guide covers Astro 5 and newer. Starwind uses the Astro adapter and the standard src/ project layout.

Requirements

Astro 5 or newer.
A project root with package.json and an astro.config.ts, .js, .mjs, or .cjs file.
A shared layout or page that can own the Starwind stylesheet and theme initializer.

Create an Astro Project

Skip this step when the Astro project already exists.

pnpm create astro@latest

npm create astro@latest

yarn create astro

Initialize Starwind

Run the command from the project root.

pnpx starwind@latest init --defaults

npx starwind@latest init --defaults

yarn dlx starwind@latest init --defaults

Starwind detects Astro from package.json or an Astro configuration file. It installs @starwind-ui/astro, creates starwind.config.json, configures the @/* alias, adds the Tailwind Vite plugin, and creates these default paths:

Purpose	Path
Styled components	`src/components/starwind`
Shared utilities	`src/lib/utils`
Starwind stylesheet	`src/styles/starwind.css`

When src/layouts/Layout.astro or src/layouts/BaseLayout.astro exists, initialization imports the stylesheet there. The minimal Astro starter has no shared layout, so its first page must own the stylesheet and theme initializer. Move those two concerns into your shared layout when you add one.

Add and Render Button

pnpx starwind@latest add button

npx starwind@latest add button

yarn dlx starwind@latest add button

The following example works as-is in the minimal Astro starter:

---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
import { Button } from "@/components/starwind/button";
import "@/styles/starwind.css";
---

<html lang="en">
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <Button>Hello from Astro</Button>
  </body>
</html>

Framework Wiring

Complete the shared manual setup with the Astro adapter, then connect those files to the Astro host as follows.

Alias

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

Tailwind Vite plugin

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

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

Stylesheet and theme initialization

Import the stylesheet and render ThemeInitScript in the document head. The script applies the saved theme before paint and supports Astro view transitions.

---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
import "@/styles/starwind.css";
---

<!doctype html>
<html lang="en">
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <slot />
  </body>
</html>

See Dark Mode for theme controls and configuration.

React Islands

The Astro adapter renders native .astro components. An Astro project can also keep React-targeted Starwind source for React islands. Initialize that secondary target explicitly:

pnpx starwind@latest init --framework react --defaults

npx starwind@latest init --framework react --defaults

yarn dlx starwind@latest init --framework react --defaults

Starwind detects the Astro host, installs Astro’s React integration and the React adapter, then keeps Astro as the primary config framework. React components go in src/components/starwind-react through componentDirs.react.

Add a component to the React target and hydrate it as an island:

pnpx starwind@latest add button --framework react

npx starwind@latest add button --framework react

yarn dlx starwind@latest add button --framework react

---
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Button } from "@/components/starwind-react/button";
import "@/styles/starwind.css";
---

<html lang="en">
  <head>
    <ThemeInitScript />
  </head>
  <body>
    <Button client:load>Hello from a React island</Button>
  </body>
</html>

This flow also adds @astrojs/react, React, React DOM, and the required JSX compiler settings when the Astro project does not already use React.

Support Boundaries

Automatic setup supports the standard Astro src/ layout and an Astro config that exports an object-form defineConfig({ ... }) call. Keep one Starwind theme initializer and stylesheet import in the shared document owner.