On this page

Next.js Installation

Starwind supports both Next.js routing systems. The CLI detects the active router and whether the application uses a root-level or src/ source tree.

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.

pnpm create next-app@latest my-app --yes

npx create-next-app@latest my-app --yes

yarn create next-app my-app --yes

The current recommended defaults create an App Router project with TypeScript, Tailwind CSS, and the @/* alias. Add --src-dir when you want src/app.

pnpm create next-app@latest my-app --no-app --yes

npx create-next-app@latest my-app --no-app --yes

yarn create next-app my-app --no-app --yes

The explicit --no-app flag selects the Pages Router while --yes accepts the remaining recommended defaults.

Initialize Starwind

cd my-app
pnpx starwind@latest init --defaults

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

cd my-app
yarn dlx starwind@latest init --defaults

Starwind reads the next and react dependencies, then checks the router files before it installs packages or changes the project. The resulting starwind.config.json keeps framework: "react"; the detected Next.js router controls the file plan.

App Router

Starwind recognizes app/layout.* and src/app/layout.*. It looks for the global stylesheet in the matching source tree, creates components and utilities beside that tree, and imports the Starwind stylesheet from the global stylesheet.

Source tree	Components	Utilities	Starwind stylesheet
Root `app/`	`components/starwind`	`lib/utils`	`styles/starwind.css`
`src/app/`	`src/components/starwind`	`src/lib/utils`	`src/styles/starwind.css`

Initialization adds ThemeInitScript to the root layout head and adds suppressHydrationWarning to <html>. The prepaint script resolves the saved theme before React hydrates.

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:

pnpx starwind@latest add button

npx starwind@latest add button

yarn dlx starwind@latest add button

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. Generated interactive Starwind components own their client boundary where their implementation needs one. Add "use client" to your component when your own code uses client-only React APIs such as state or event handlers.

App Router framework wiring

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

@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

Starwind recognizes pages/_app.* and src/pages/_app.*. The custom App owns the one global CSS import for the application. The prepaint theme script belongs in _document.*.

Source tree	Components	Utilities	Starwind stylesheet
Root `pages/`	`components/starwind`	`lib/utils`	`styles/starwind.css`
`src/pages/`	`src/components/starwind`	`src/lib/utils`	`src/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.

import type { AppProps } from "next/app";

import "@/styles/globals.css";

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

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:

pnpx starwind@latest add button

npx starwind@latest add button

yarn dlx starwind@latest add button

import { Button } from "@/components/starwind/button";

export default function Home() {
  return <Button>Hello from the Pages Router</Button>;
}

Pages Router framework wiring

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

Pages Router component styles

Next.js Pages requires global component CSS to flow through _app. Some generated components have a local styles.css file. Starwind removes those local JavaScript imports and maintains their CSS imports inside the configured Starwind stylesheet between these markers:

/* 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.

Support Boundaries

Automatic setup requires one complete supported router shape. An App Router project needs its root layout and global stylesheet. A Pages Router project needs _app and a global stylesheet. Starwind stops during preflight when these files are incomplete.

See Dark Mode for theme behavior in both routers.