Skip to main content

Starwind UI v3.0 is now available! Migration guide

TanStack Start Installation

Use this guide for TanStack Start with Vite. Projects that use Rsbuild need manual setup.

Requirements

  • React and React DOM 18 or newer.
  • @tanstack/react-start in the project dependencies.
  • vite.config.* with the existing @tailwindcss/vite plugin.
  • src/routes/__root.* and an existing src/styles.css or src/app.css stylesheet.

Create a TanStack Start Project

Skip this step if you already have a project. The default TanStack Start starter includes Vite and Tailwind CSS.

Install with the CLI

Starwind detects @tanstack/react-start, the Vite config, src/routes/__root.*, and the global stylesheet before it changes the project. It installs the React package and uses these paths:

PurposePath
Styled componentssrc/components/starwind
Shared utilitiessrc/lib/utils
Starwind stylesheetsrc/styles/starwind.css
Theme scriptsrc/routes/__root.*

The CLI adds Starwind to your global stylesheet. It moves the Tailwind import into starwind.css so Tailwind loads once, and keeps your other CSS imports in place.

Add and Render Button

src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
import { Button } from "@/components/starwind/button";
export const Route = createFileRoute("/")({
component: Home,
});
function Home() {
return <Button>Hello from TanStack Start</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. Set @/* to ./src/* and keep the framework’s existing Vite plugins. The current starter config includes the following plugin order:

vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import { devtools } from "@tanstack/devtools-vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
resolve: { tsconfigPaths: true },
plugins: [devtools(), tailwindcss(), tanstackStart(), viteReact()],
});

Import Starwind from the existing application stylesheet.

src/styles.css
@import "./styles/starwind.css";
/* Existing application styles remain here. */

If your root route already has a script that applies the saved theme, keep it. Otherwise, add ThemeInitScript before HeadContent, as shown here:

src/routes/__root.tsx
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";
export const Route = createRootRoute({
shellComponent: RootDocument,
});
function RootDocument({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<ThemeInitScript />
<HeadContent />
</head>
<body>
{children}
<Scripts />
</body>
</html>
);
}

The CLI recognizes both ThemeInitScript and the older inline Starwind theme script. Keep one theme script in src/routes/__root.*.

Custom Project Setup

The CLI needs Vite with @tailwindcss/vite already configured. It checks your project before installing packages or editing files. For Rsbuild or a custom setup, configure Starwind manually.

See Dark Mode for theme controls.