Skip to main content

Starwind UI v3.0 is now available! Migration guide

Next.js Installation

Starwind works with the App Router and Pages Router. The CLI detects which one you use, including projects that keep their app files in src/.

Requirements

  • React and React DOM 18 or newer.
  • A Next.js project with an App Router root layout or a Pages Router custom App.
  • A supported global stylesheet for the selected router.

Create a Next.js Project

Skip this step when the project already exists.

Install with the CLI

The CLI checks your Next.js project, installs the Starwind packages, and sets up the files for your router. It sets framework: "react" in starwind.config.json.

App Router

The CLI makes the setup changes described here. Use the component example to add your own UI.

The CLI finds your layout in app/ or src/app/ and adds Starwind to the global stylesheet. It puts components and styles in the matching folders:

Source treeComponentsUtilitiesStarwind stylesheet
Root app/components/starwindlib/utilsstyles/starwind.css
src/app/src/components/starwindsrc/lib/utilssrc/styles/starwind.css

The CLI adds ThemeInitScript to the layout’s <head> so the saved theme is applied before the page appears. It also adds suppressHydrationWarning to <html>.

app/layout.tsx
import { ThemeInitScript } from "@starwind-ui/react/theme";
import "./globals.css";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<ThemeInitScript />
</head>
<body>{children}</body>
</html>
);
}

Add and render Button from an App Router page:

app/page.tsx
import { Button } from "@/components/starwind/button";
export default function Page() {
return <Button>Hello from the App Router</Button>;
}

App Router pages are Server Components by default. Starwind adds "use client" to its components where needed. Add it to your own component when you use React state or event handlers.

App Router Manual Setup

The CLI handles this setup. Follow these steps if you prefer to configure the files yourself.

Complete the shared manual setup with the React package. Configure Tailwind CSS v4 through the Next.js PostCSS integration, then import the Starwind stylesheet from the global stylesheet.

app/globals.css
@import "../styles/starwind.css";
/* Application styles */

Set @/* to ./src/* for a src/ tree or ./* for a root tree. Place ThemeInitScript in the root layout head as shown above.

Pages Router

The CLI makes the setup changes described here. Use the component example to add your own UI.

Import global styles in pages/_app.* or src/pages/_app.*. Put the theme script in _document.*. The CLI sets up both for you.

Source treeComponentsUtilitiesStarwind stylesheet
Root pages/components/starwindlib/utilsstyles/starwind.css
src/pages/src/components/starwindsrc/lib/utilssrc/styles/starwind.css

Initialization adds the Starwind stylesheet to the existing global stylesheet used by _app. It updates an existing _document.* with ThemeInitScript, or creates _document beside _app when one does not exist.

pages/_app.tsx
import type { AppProps } from "next/app";
import "@/styles/globals.css";
export default function App({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />;
}
pages/_document.tsx
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Head, Html, Main, NextScript } from "next/document";
export default function Document() {
return (
<Html suppressHydrationWarning>
<Head>
<ThemeInitScript />
</Head>
<body>
<Main />
<NextScript />
</body>
</Html>
);
}

Add and render Button from a page:

pages/index.tsx
import { Button } from "@/components/starwind/button";
export default function Home() {
return <Button>Hello from the Pages Router</Button>;
}

Pages Router Manual Setup

The CLI handles this setup. Follow these steps if you prefer to configure the files yourself.

Complete the shared manual setup with the React package. Use the root or src/ paths from the table above. Import the Starwind stylesheet through the global stylesheet imported by _app, then render ThemeInitScript from _document as shown above.

Pages Router component styles

Next.js Pages Router loads global CSS through _app. When a Starwind component includes a styles.css file, the CLI adds its import to the Starwind stylesheet between these comments:

/* Starwind Next.js Pages component styles: start */
@import "../components/starwind/example/styles.css";
/* Starwind Next.js Pages component styles: end */

Keep that managed block in place. The CLI updates it when components are added, updated, or removed.

Custom Project Setup

Before running the CLI, make sure your App Router project has a root layout and global stylesheet. Pages Router projects need _app and a global stylesheet. The CLI checks for these files before it installs packages or makes changes.

See Dark Mode for theme behavior in both routers.