# Next.js

Use the kit in a React 19 App Router application.

## Prepare the application

For a new application, create a TypeScript App Router project with Tailwind, a `src` directory and the `@/*` alias:

```bash
pnpm dlx create-next-app@16.3.4 my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-pnpm --yes
cd my-app
```

With npm, replace `pnpm dlx` with `npx` and `--use-pnpm` with `--use-npm`. Skip creation for an existing React 19 App Router application. The kit does not require a Siteplane UI runtime package.

Install Tailwind’s PostCSS integration if your project does not already have it:

```bash
pnpm add -D tailwindcss @tailwindcss/postcss
```

```js title="postcss.config.mjs"
export default { plugins: { "@tailwindcss/postcss": {} } };
```

## Create components.json

Write this file to the application directory instead of running `shadcn init`, which would write a shadcn theme over the kit’s styles. If the application already has a `components.json`, keep it and add the `@siteplane` entry to its `registries`.

```json title="components.json"
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks",
    "utils": "@/siteplane/system/utils/cn"
  },
  "registries": {
    "@siteplane": "https://ui.siteplane.io/registry/{name}.json"
  }
}
```

## Install the source

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/button
pnpm add @fontsource-variable/inter
```

Replace the contents of `src/app/globals.css` with the kit import below. The starter styles that `create-next-app` writes there set their own colors and fonts, which would override the kit’s. An application with its own styles keeps them below the import, as [Installation](/docs/installation/#load-styles-and-typography) describes.

```css title="src/app/globals.css"
@import "../siteplane/system/styles/base.css";
@source "..";
```

Replace `src/app/layout.tsx` with this layout, which loads Inter, the kit’s typeface, and the global CSS. It replaces the starter’s font setup; to set the kit in another typeface, follow [Typeface](/docs/customization/theming/#typeface). `data-theme="light"` sets the theme; use `dark` for the dark theme. The kit stays light until an application sets `data-theme="dark"` or the `dark` class, and it does not follow the operating system by itself.

```tsx title="src/app/layout.tsx"
import "@fontsource-variable/inter";
import "./globals.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" data-theme="light">
      <body>{children}</body>
    </html>
  );
}
```

## Render your first component

```tsx title="src/app/page.tsx"
import { Button } from "@/siteplane/components/button";

export default function Page() {
  return (
    <main className="p-8">
      <Button>Continue</Button>
    </main>
  );
}
```

For an interactive example, save the complete code from a component preview as `src/components/example.tsx`, then import and render its default export in the page. Examples include `"use client"`; keep event handlers and local state inside that client boundary. Do not pass functions from a Server Component into a client control.

## Application providers

The default configuration needs no provider. [SiteplaneUIProvider and SiteplaneLocaleProvider](/docs/customization/providers/) are Client Components, so the root layout can stay a Server Component and render them with serializable props such as `controlSize="lg"` or `locale="en-GB"`. A theme controller needs its own client wrapper; the [application-wide dark-mode guide](/docs/customization/theming/#application-wide-dark-mode) shows the provider and root-layout wiring.

Start the development server with `pnpm dev` (npm: `npm run dev`) and check the rendered component and an open overlay. Unstyled content usually means the global CSS import or Tailwind scanning is missing; changing component markup will not fix it.