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.jsonand anastro.config.ts,.js,.mjs, or.cjsfile. - 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.
pnpm create astro@latestnpm create astro@latestyarn create astroInstall with the CLI
Run the command from the project root.
pnpx starwind@latest init --defaultsnpx starwind@latest init --defaultsyarn dlx starwind@latest init --defaultsWhat 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:
| Purpose | Path |
|---|---|
| Styled components | src/components/starwind |
| Shared utilities | src/lib/utils |
| Starwind stylesheet | src/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
pnpx starwind@latest add buttonnpx starwind@latest add buttonyarn dlx starwind@latest add buttonFor 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:
---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
{ "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 the page appears and keeps it after Astro page 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.
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.