# Vite React Installation

This guide covers a standard Vite application with React 18 or newer. It also applies when React
Router is used as a client-side library inside that Vite application.

## Requirements

- React and React DOM 18 or newer.
- A supported `vite.config.*` file.
- A `src/main.tsx`, `.jsx`, `.ts`, or `.js` entry file.
- A global stylesheet imported by the application.

## Create a Vite React Project

Skip this step when the project already exists.

```bash
npm create vite@latest my-app -- --template react-ts
```

## Initialize Starwind

```bash
cd my-app
npx starwind@latest init --defaults
```

Starwind detects React from `package.json`, then confirms the Vite host through `vite.config.*` and
`src/main.*`. It installs `@starwind-ui/react`, creates `starwind.config.json`, configures the
`@/*` alias, updates the Vite plugin list, and imports the Starwind stylesheet from the React entry.
For a JavaScript starter, it also creates `tsconfig.json` with `allowJs` and JSX settings so the
generated TypeScript component source can compile beside `.js` and `.jsx` application files.

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

## Add and Render Button

```bash
npx starwind@latest add button
```

```tsx title="src/App.tsx"
import { Button } from "@/components/starwind/button";

export default function App() {
  return <Button>Hello from Vite</Button>;
}
```

## Framework Wiring

Complete the [shared manual setup](/docs/getting-started/manual-setup/) with the React adapter. The
Vite config then needs Tailwind, the `@` alias, and a prepaint theme plugin based on
`getThemeInitScript`.

```ts title="vite.config.ts"
import { fileURLToPath } from "node:url";

import { getThemeInitScript } from "@starwind-ui/react/theme";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

function starwindThemeInitPlugin() {
  return {
    name: "starwind-theme-init",
    transformIndexHtml() {
      return [
        {
          tag: "script",
          attrs: { "data-starwind-theme-init": "" },
          children: getThemeInitScript(),
          injectTo: "head-prepend" as const,
        },
      ];
    },
  };
}

export default defineConfig({
  resolve: {
    alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
  },
  plugins: [starwindThemeInitPlugin(), tailwindcss(), react()],
});
```

Add the matching TypeScript alias to `tsconfig.app.json` when that file exists.

```json title="tsconfig.app.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

Import the generated stylesheet from the detected entry file.

```tsx title="src/main.tsx"
import "@/styles/starwind.css";
```

See [Dark Mode](/docs/getting-started/dark-mode/#vite-react) for the theme API.

## Support Boundaries

The automatic Vite update expects an object-form `defineConfig({ ... })` export with a plugin array
that Starwind can update. A Vite SPA that uses React Router in declarative or data mode stays on
this guide. React Router framework mode has a separate
[React Router guide](/docs/frameworks/react-router/).