Layout UI

Next.js

Set up Layout UI in a new or existing Next.js project using the App Router, Tailwind v4, and TypeScript strict mode.

New project

  1. Create a Next.js app

    Bootstrap a new project with the latest Next.js and accept the TypeScript and Tailwind v4 prompts:

    npx create-next-app@latest my-app --typescript --tailwind --app --src-dir no
cd my-app

  2. Verify Tailwind v4 is installed

    Next.js scaffolding installs Tailwind v4 automatically. Confirm app/globals.css starts with the Tailwind v4 import:

    @import "tailwindcss";

    If you see @tailwind base; instead, you have Tailwind v3. Upgrade: npm install tailwindcss@latest @tailwindcss/postcss@latest.

  3. Confirm path aliases

    The scaffolded tsconfig.json should already have the @/* alias. Check:

    {
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

  4. Initialise shadcn

    Run the shadcn init command to create a components.json. The -b flag picks the primitives library and -p picks a starting preset; any preset works because Layout UI themes replace it:

    npx shadcn@latest init -y -b base -p nova

  5. Add the Layout registry

    Open components.json and add the Layout registry:

    {
  "registries": {
    "@layout": "https://layout.design/r/{name}.json"
  }
}

  6. Install the theme and your first component

    Install the Layout theme (sets the full token contract) then your first component:

    npx shadcn add @layout/theme-layout
npx shadcn add @layout/button

    The theme token file is added to your globals.css. The button lands in components/ui/button.tsx.

  7. Use the component

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

export default function Page() {
  return <Button>Get started</Button>;
}

Existing project

If you already have a Next.js project with shadcn configured, skip to step 5 above: add the Layout registry to components.json and run npx shadcn add @layout/theme-layout.

If your project uses Tailwind v3 you will need to migrate to v4 first, as the Layout token contract uses @theme inline, CSS layers, and @custom-variant which are v4-only.