Next.js

Prepare the application

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

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:

pnpm add -D tailwindcss @tailwindcss/postcss

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.

{
  "$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

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 describes.

@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. 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.

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

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