Project Scaffolding

Quick Start: New Project from Scratch

# 1. Create Next.js project
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir

# 2. Initialize shadcn/ui (Base UI is the default base; -b radix|aria to switch;
#    default preset is base-nova)
cd my-app
npx shadcn@latest init

# Or one step — init scaffolds the Next.js app too:
npx shadcn@latest init -t next -n my-app

# 3. Install core components
npx shadcn@latest add button card input form dialog dropdown-menu toast tabs

shadcn studio Templates

shadcn studio offers 20+ production-ready templates (requires Pro license). Official templates can also be scaffolded via npx shadcn create presets:

Using a Template

1. Download the template ZIP from shadcnstudio.com
2. Extract to your project directory
3. Install dependencies: pnpm install
4. Start dev server: pnpm dev

Templates come pre-configured with:

• Next.js App Router with TypeScript
• Tailwind CSS and shadcn/ui components
• Responsive layouts (mobile-first)
• Dark mode support
• Professional page structure

Recommended Project Structure

src/
├── app/                        # App Router pages
│   ├── layout.tsx              # Root layout (theme provider, fonts)
│   ├── page.tsx                # Home page
│   ├── (auth)/                 # Auth route group
│   │   ├── login/page.tsx
│   │   └── signup/page.tsx
│   ├── (dashboard)/            # Dashboard route group
│   │   ├── layout.tsx          # Dashboard layout with sidebar
│   │   ├── page.tsx            # Dashboard home
│   │   └── settings/page.tsx
│   └── (marketing)/            # Marketing route group
│       ├── layout.tsx          # Marketing layout with navbar
│       └── page.tsx            # Landing page
├── components/
│   ├── ui/                     # shadcn/ui primitives (auto-generated)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── ...
│   ├── blocks/                 # shadcn studio blocks (moved from shadcn-studio/)
│   │   ├── hero-section.tsx
│   │   └── pricing-table.tsx
│   ├── forms/                  # Form compositions
│   │   ├── login-form.tsx
│   │   └── settings-form.tsx
│   ├── layout/                 # Layout components
│   │   ├── site-header.tsx
│   │   ├── site-footer.tsx
│   │   ├── sidebar-nav.tsx
│   │   └── mobile-nav.tsx
│   └── features/               # Feature-specific compositions
│       ├── user-profile-card.tsx
│       └── data-table.tsx
├── lib/
│   ├── utils.ts                # cn() helper (created by shadcn init)
│   └── validations.ts          # Zod schemas for forms
├── hooks/                      # Custom React hooks
│   └── use-media-query.ts
├── styles/
│   └── globals.css             # Theme CSS variables
└── types/                      # TypeScript type definitions
    └── index.ts

Key Organization Rules

1. components/ui/ -- Only auto-generated shadcn/ui files. Do not put custom components here
2. components/blocks/ -- Moved studio blocks and your own larger UI sections
3. components/forms/ -- Form compositions that combine shadcn form primitives
4. components/layout/ -- Shared layout elements (header, footer, sidebar, navigation)
5. components/features/ -- Domain-specific component compositions

components.json Configuration

The components.json file controls where components are installed and how paths resolve:

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

("config": "" is correct for Tailwind v4 — v3 projects point it at tailwind.config.ts.) Run npx shadcn@latest info to print the project's resolved configuration.

Key Fields

Component Architecture Patterns

Atomic Design Mapping

Server vs Client Component Split

Server Components (default):           Client Components ('use client'):
├── Layout shells                       ├── Interactive forms
├── Data display (cards, tables)        ├── Theme toggle
├── Static content blocks               ├── Dropdown menus
├── Navigation structure                ├── Dialogs/modals
└── Page-level data fetching            ├── Tabs with state
                                        ├── Toast notifications
                                        └── Any component using hooks

Rule: Keep components as Server Components until they need interactivity. Wrap only the interactive part in 'use client'.

Barrel Exports Pattern

Create index files for component groups:

// components/layout/index.ts
export { SiteHeader } from "./site-header"
export { SiteFooter } from "./site-footer"
export { SidebarNav } from "./sidebar-nav"
export { MobileNav } from "./mobile-nav"

Usage:

import { SiteHeader, SiteFooter } from "@/components/layout"

Monorepo Setup (Turborepo)

For shared component libraries across multiple Next.js apps:

packages/
├── ui/                         # Shared shadcn/ui components
│   ├── src/components/ui/      # shadcn primitives
│   ├── src/lib/utils.ts        # cn() helper
│   ├── components.json         # shadcn config
│   ├── package.json
│   └── tsconfig.json
apps/
├── web/                        # Main Next.js app
│   └── components/             # App-specific compositions
└── admin/                      # Admin Next.js app
    └── components/             # Admin-specific compositions

The ui package exports shared shadcn/ui components. Each app imports them and adds app-specific compositions.

What This Skill Does NOT Cover

• Installing specific components -- see component-registry skill
• Theme and color configuration -- see theme-configuration skill
• Initial shadcn/ui setup -- see setup skill
• Development patterns (routing, data fetching) -- see nextjs-dev plugin