Skip to main content

Starwind UI v3.0 is now available! Migration guide

Vite React Installation

Use this guide for Vite with React 18 or newer, including apps that use React Router as a library.

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.

Install with the CLI

The CLI checks your React and Vite setup, then installs the Starwind packages. It adds starwind.config.json, sets up the @/* import shortcut, and configures Tailwind and the theme script. It also imports the Starwind stylesheet in src/main.*.

For JavaScript projects, it enables allowJs in the TypeScript settings so you can use Starwind’s components alongside your .js and .jsx files.

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

Add and Render Button

src/App.tsx
import { Button } from "@/components/starwind/button";
export default function App() {
return <Button>Hello from Vite</Button>;
}

Manual Setup

Follow these steps to set up Starwind by hand. You can also use them to check the files changed by the CLI.

Complete the shared manual setup with the React package. The Vite config below adds Tailwind, the @ import shortcut, and a script that applies the saved theme before the page appears.

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.

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

Import the Starwind stylesheet in src/main.tsx or your app’s equivalent entry file.

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

See Dark Mode for the theme API.

Custom Project Setup

The CLI can update a Vite config written as export default defineConfig({ ... }), with plugins listed in the plugins array. For other config styles, use the manual steps above.

If you added React Router to a Vite app, keep using this guide. For React Router framework mode, use the React Router guide.