Skip to main content

Starwind UI v3.0 is now available! Migration guide

Astro Installation

Use this guide for Astro 5 or newer with the usual src/ folder structure.

Requirements

  • Astro 5 or newer.
  • A project root with package.json and an astro.config.ts, .js, .mjs, or .cjs file.
  • A layout or page where you can import styles and add the theme script.

Create an Astro Project

Skip this step when the Astro project already exists.

Install with the CLI

Run the command from the project root.

What the CLI Does

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:

PurposePath
Styled componentssrc/components/starwind
Shared utilitiessrc/lib/utils
Starwind stylesheetsrc/styles/starwind.css

The CLI imports the stylesheet into src/layouts/Layout.astro or src/layouts/BaseLayout.astro. If neither exists, it uses src/pages/index.astro. If it cannot update a supported file, it prints the import for you to add.

Add and Render Button

For the minimal Astro starter, use this page. The optional ThemeInitScript applies the saved theme before the page appears. Keep the stylesheet import added by the CLI:

src/pages/index.astro
---
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>

Manual Setup

Use this section if you are setting up Starwind by hand or need to check a custom configuration. After a successful CLI install, continue with your component example and any extra steps noted above.

Complete the shared manual setup with the Astro package, then update the files shown below.

Alias

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

Tailwind Vite plugin

astro.config.mjs
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 the page appears and keeps it after Astro page transitions.

src/layouts/Layout.astro
---
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.

Framework Islands

Use these guides to add another framework’s Starwind components to your Astro project:

Support Boundaries

The CLI works with the usual Astro src/ folder structure and a config written as export default defineConfig({ ... }). If your project uses a different setup, follow the manual steps above.

Put the stylesheet import and ThemeInitScript in your shared layout so they apply to every page that uses it.