Setup

Prerequisites Check

Before initializing shadcn/ui, verify the project meets these requirements:

If Tailwind CSS is not installed:

# For new projects, create-next-app includes Tailwind by default:
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir

# For existing projects without Tailwind:
npm install -D tailwindcss @tailwindcss/postcss postcss

Step 1: Initialize shadcn/ui

Run the init command in the project root:

npx shadcn@latest init

The CLI v4 init command (alias create) supports:

• -t next|start|vite|react-router|laravel|astro -- project template
• -b base|radix|aria -- component base (Base UI is the default since July 2026; Radix and React Aria remain fully supported)
• -p <preset> -- style preset
• -d -- accept defaults (equivalent to --template=next --preset=base-nova)
• --css-variables (default true), --rtl, --pointer (adds cursor: pointer CSS for buttons), --monorepo

Base colors are now neutral | stone | zinc | mauve | olive | mist | taupe. Visual styles are the 8 official presets — Vega (classic look), Nova (compact, default), Maia (rounded), Lyra (sharp/mono), Mira (dense), Luma, Rhea, Sera — chosen via preset or the visual builder at https://ui.shadcn.com/create (npx shadcn create). Apply a preset to an existing project with shadcn apply <preset-code> [--only theme|font].

This creates:

• components.json -- Configuration file for the shadcn CLI
• lib/utils.ts (or src/lib/utils.ts) -- The cn() class merge utility
• Updates globals.css with CSS variables for the chosen theme
• Installs dependencies: clsx, tailwind-merge, class-variance-authority

Step 2: Verify Base Installation

Check these files exist and are correct:

1. components.json -- Should contain ("style": "new-york" is still the standard value; "default" is deprecated). For Tailwind v4, tailwind.config is left blank:

   {
     "$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
     },
     "aliases": {
       "components": "@/components",
       "utils": "@/lib/utils"
     }
   }
   

   (Tailwind v3 projects keep "config": "tailwind.config.ts".)

2. lib/utils.ts -- Should export the cn() helper:

   import { type ClassValue, clsx } from "clsx"
   import { twMerge } from "tailwind-merge"
   
   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs))
   }
   

3. globals.css -- Should contain :root and .dark CSS variable blocks

4. Font variable check -- After init, verify globals.css does not contain circular font references:

   • --font-sans: var(--font-sans) — wrong, circular reference, browser falls back to system font
   • --font-sans: var(--font-geist-sans) — correct, maps to the CSS variable set by next/font in layout.tsx

   If the project uses Geist (Next.js default), ensure layout.tsx declares the font variable:

   import { Geist } from "next/font/google"
   const geistSans = Geist({ subsets: ["latin"], variable: "--font-geist-sans" })
   

   And globals.css maps it (inside @theme inline):

   --font-sans: var(--font-geist-sans);
   

Step 3: Configure shadcn studio Registries

To access shadcn studio components, blocks, pages, and themes, add the studio registries to components.json:

{
  "registries": {
    "@shadcn-studio": "https://shadcnstudio.com/r/{style}/{name}.json",
    "@ss-components": "https://shadcnstudio.com/r/components/{style}/{name}.json",
    "@ss-blocks": "https://shadcnstudio.com/r/blocks/{style}/{name}.json",
    "@ss-pages": "https://shadcnstudio.com/r/pages/{style}/{name}.json",
    "@ss-themes": "https://shadcnstudio.com/r/themes/{name}.json"
  }
}

Or use the native one-liner instead of hand-editing:

npx shadcn registry add @shadcn-studio=https://shadcnstudio.com/r/{style}/{name}.json @ss-components=https://shadcnstudio.com/r/components/{style}/{name}.json @ss-blocks=https://shadcnstudio.com/r/blocks/{style}/{name}.json @ss-pages=https://shadcnstudio.com/r/pages/{style}/{name}.json @ss-themes=https://shadcnstudio.com/r/themes/{name}.json

This enables five namespace registries:

• @shadcn-studio -- Free studio content (new namespace)
• @ss-components -- Component variants (buttons, cards, inputs, etc.)
• @ss-blocks -- Pre-built UI blocks (hero sections, dashboards, forms, etc.)
• @ss-pages -- Full pre-built pages (new namespace)
• @ss-themes -- Theme presets (color schemes, typography, etc.)

Step 4: Configure Premium Access (Optional)

For premium shadcn studio content, create a .env file in the project root:

EMAIL=your-email@example.com
LICENSE_KEY=your-license-key

Add .env to .gitignore if not already present:

echo ".env" >> .gitignore

Premium access requires converting the registry entries in components.json to objects with params — the CLI expands ${EMAIL} and ${LICENSE_KEY} from the environment:

"@ss-components": {
  "url": "https://shadcnstudio.com/r/components/{style}/{name}.json",
  "params": { "email": "${EMAIL}", "license_key": "${LICENSE_KEY}" }
}

Free components and blocks work without credentials. Premium content requires a shadcn studio license (Basic $99, Pro $199, Team $449, Enterprise $849).

Step 5: Test Component Installation

Verify the setup works by installing a test component:

# Standard shadcn/ui component:
npx shadcn@latest add button

# shadcn studio component (if registries configured) — namespaced address:
npx shadcn@latest add @ss-components/button-01

The --registry flag no longer exists in CLI v4 — installation from any registry uses namespaced addresses (@namespace/item).

Check that:

• Component file created at components/ui/button.tsx (or src/components/ui/button.tsx)
• No import errors when building: npm run build
• Component renders correctly in the browser

Step 6: Configure Community Registries (Optional)

The official shadcn MCP only searches registries listed in components.json. To unlock search across all 260+ community registries (267 as of Aug 2026), populate them from the official endpoint:

curl -s https://ui.shadcn.com/r/registries.json

This returns a JSON array with name, url, homepage, description for every registry. Add entries with the native command:

npx shadcn registry add @magicui=https://magicui.design/r/{name} @aceternity=https://ui.aceternity.com/registry/{name}.json

Or add them to the "registries" field in components.json directly:

{
  "registries": {
    "@magicui": "https://magicui.design/r/{name}",
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

Use the /add-registries command to do this in bulk automatically — it fetches the endpoint, parses all entries, and merges them into components.json.

Install the Official shadcn Skill

The official shadcn skill reads components.json and enables Claude to discover components from configured registries:

pnpm dlx skills add shadcn/ui

This creates skill files that Claude Code loads automatically when components.json is detected. The skill runs shadcn info --json to read the project's resolved configuration.

Tailwind v3 vs v4 Notes

If using Tailwind v4, ensure postcss.config.mjs uses @tailwindcss/postcss:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

What This Skill Does NOT Cover

• Development patterns (App Router, Server Components) -- see nextjs-dev plugin
• MCP server configuration -- see mcp-tools skill
• Theme customization beyond initial setup -- see theme-configuration skill
• Browsing and installing specific components -- see component-registry skill
• Searching and installing from community registries -- see component-search skill