# 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.
```bash
npm create astro@latest
```
## Initialize Starwind
Run the command from the project root.
```bash
npx 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
```bash
npx starwind@latest add button
```
The following example works as-is in the minimal Astro starter:
```astro title="src/pages/index.astro"
```
## Framework Wiring
Complete the [shared manual setup](/docs/getting-started/manual-setup/) with the Astro adapter, then
connect those files to the Astro host as follows.
### Alias
```json title="tsconfig.json"
{
"extends": "astro/tsconfigs/strict",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
```
### Tailwind Vite plugin
```js title="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 paint and supports Astro view transitions.
```astro title="src/layouts/Layout.astro"
---
import { ThemeInitScript } from "@starwind-ui/astro/theme";
import "@/styles/starwind.css";
---
```
See [Dark Mode](/docs/getting-started/dark-mode/#astro) 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:
```bash
npx 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:
```bash
npx starwind@latest add button --framework react
```
```astro title="src/pages/index.astro"
---
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Button } from "@/components/starwind-react/button";
import "@/styles/starwind.css";
---
```
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.