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.

Vue Islands (Beta)

Info

Vue 3.5 support is in public beta. It includes Primitive adapters and editable Styled components. APIs can change during the 0.x release series. Report beta issues through the Starwind UI issue tracker.

Initialize the Vue target explicitly in your Astro project:

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

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

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

Starwind installs @starwind-ui/vue@beta, Vue 3.5 or newer, and the Astro Vue integration when needed. Astro remains the primary framework. Vue components go in src/components/starwind-vue through componentDirs.vue, and share the Astro stylesheet.

In an Astro project, starwind add uses Astro unless you pass --framework vue. A componentDirs.vue entry sets the Vue output directory; it does not select Vue for the command. Use the Vue installation tab on component pages. Import the generated .vue components into Vue files and use an Astro client:* directive when rendering the Vue island from an Astro page.

pnpx starwind@latest add button --framework vue

npx starwind@latest add button --framework vue

yarn dlx starwind@latest add button --framework vue

<script setup lang="ts">
import { Button } from "@/components/starwind-vue/button";
</script>

<template>
  <Button>Hello from Vue</Button>
</template>

Render interactive Vue components inside one hydrated island. Keep composed Dialog or form parts inside the same .vue component so they share Vue context.

---
import Layout from "@/layouts/Layout.astro";
import WelcomeButton from "@/components/WelcomeButton.vue";
---

<Layout>
  <WelcomeButton client:load />
</Layout>

The layout owns the stylesheet and Astro ThemeInitScript from the setup above. For manual integration, follow Astro’s Vue guide. See the Vue examples on Dialog and Input for models and events.

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.