# 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.
```bash
npx create-next-app@latest 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`.
```bash
npx create-next-app@latest my-app --no-app --yes
```
The explicit `--no-app` flag selects the Pages Router while `--yes` accepts the remaining
recommended defaults.
## Initialize Starwind
```bash
cd my-app
npx 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 ``. The prepaint script resolves the saved theme before React
hydrates.
```tsx title="app/layout.tsx"
import { ThemeInitScript } from "@starwind-ui/react/theme";
import "./globals.css";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Add and render `Button` from an App Router page:
```bash
npx starwind@latest add button
```
```tsx title="app/page.tsx"
import { Button } from "@/components/starwind/button";
export default function Page() {
return ;
}
```
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](/docs/getting-started/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.
```css title="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
Starwind recognizes `pages/_app.*` and `src/pages/_app.*`. The custom App owns the one global CSS
| 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.
```tsx title="pages/_app.tsx"
import type { AppProps } from "next/app";
import "@/styles/globals.css";
export default function App({ Component, pageProps }: AppProps) {
return ;
}
```
```tsx title="pages/_document.tsx"
import { ThemeInitScript } from "@starwind-ui/react/theme";
import { Head, Html, Main, NextScript } from "next/document";
export default function Document() {
return (
);
}
```
Add and render `Button` from a page:
```bash
npx starwind@latest add button
```
```tsx title="pages/index.tsx"
import { Button } from "@/components/starwind/button";
export default function Home() {
return ;
}
```
### Pages Router framework wiring
Complete the [shared manual setup](/docs/getting-started/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:
```css
/* 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](/docs/getting-started/dark-mode/#nextjs) for theme behavior in both routers.