Claude Code Guide — Next.js + Shadcn Stack

Prečo potrebujete konfiguráciu?

Kľúčový problém: AI modely majú často tréningové dáta, ktoré zaostávajú za novinkami Next.js 15 (Server Actions, React Compiler). Bez správnej konfigurácie model preferuje zastarané vzory ako pages/ router.

❌ Bez konfigurácie

• Generuje pages/api namiesto Server Actions
• Importuje z @shadcn/ui (neexistuje)
• Používa getServerSideProps
• Tvrdé kódovanie farieb (bg-red-500)

✅ S konfiguráciou

• Používa App Router + Server Actions
• Správne cesty @/components/ui
• React Server Components
• Sémantické tokeny (bg-destructive)

📊 Overené výsledky

Repozitár wsimmonds/claude-nextjs-skills dosiahol na Vercel Next.js evaloch:

32%

Bez skills

→

78%

So skills

🚀 Inštalácia

1

Vytvorenie projektu

# Vytvor Next.js projekt s TypeScript a Tailwind
npx create-next-app@latest my-saas \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

cd my-saas

2

Inštalácia Shadcn/UI

# Inicializuj shadcn
npx shadcn@latest init

# Pridaj základné komponenty
npx shadcn@latest add button card input form

💡 Shadcn nie je npm balík - komponenty sa kopírujú priamo do components/ui/

3

Generovanie Claude Code konfigurácie

# Použitie claude-config-composer (odporúčané)
npx claude-config-composer nextjs-15 shadcn tailwindcss drizzle vercel-ai-sdk

# Alebo interaktívny režim
npx claude-config-composer

✅ Toto vygeneruje kompletnú .claude/ štruktúru s 40+ agentmi a 25+ commands

4

Voliteľné: Next.js Skills

# Pridaj eval-tested Next.js skills
git clone https://github.com/wsimmonds/claude-nextjs-skills.git /tmp/nextjs-skills
cp -r /tmp/nextjs-skills/* .claude/skills/

Tieto skills zvýšili eval score z 32% na 78%

📁 Štruktúra .claude/

.claude/
├── settings.json           # Hlavná konfigurácia hooks
├── CLAUDE.md               # Ústava agenta
│
├── agents/                 # Špecializovaní agenti
│   ├── frontend-architect.md
│   ├── database-specialist.md
│   ├── ui-designer.md
│   └── performance-optimizer.md
│
├── commands/               # Vlastné príkazy
│   ├── create-page.md
│   ├── add-component.md
│   └── optimize-styles.md
│
├── hooks/                  # Automatizačné skripty
│   ├── typescript-check.sh
│   ├── format-code.sh
│   └── validate-components.sh
│
└── skills/                 # Modulárna dokumentácia
    ├── SKILL.md            # Navigačný index
    └── resources/
        ├── app-router.md
        ├── server-components.md
        └── shadcn-patterns.md

🤖 Agenti

frontend-architect	RSC, Streaming, Suspense
database-specialist	Drizzle schémy, migrácie
ui-designer	Tailwind + Shadcn theming
performance-optimizer	Bundle analysis, Core Web Vitals

⚡ Commands

/create-page	page.tsx + layout.tsx + loading.tsx
/add-component	Obaluje npx shadcn add
/optimize-styles	Analýza Tailwind tried
/analyze-performance	Bundle report

📜 CLAUDE.md — Ústava Agenta

Súbor CLAUDE.md definuje pravidlá, ktoré agent "číta" pri každom obnovení kontextu. Pre Next.js stack je kritické správne uzemnenie.

# CLAUDE.md - Next.js 15 + Shadcn Project

## Technologický Stack
- Next.js 15 (App Router, NIE Pages Router)
- React 19 (Server Components by default)
- Shadcn/UI (komponenty v @/components/ui)
- TailwindCSS 3.4 (sémantické tokeny)
- Drizzle ORM (PostgreSQL)

## MUSÍŠ dodržiavať:
1. Používaj App Router (`app/` directory) pre všetky routy
2. Preferuj Server Components, `'use client'` len keď nutné
3. Používaj Server Actions (`'use server'`) namiesto API routes
4. Import shadcn z `@/components/ui/[component]`
5. Používaj sémantické farby (`bg-primary`, `bg-destructive`)

## NIKDY nerob:
- NEVYTVÁRAJ `pages/api/` routes
- NEPOUŽÍVAJ `getServerSideProps` ani `getStaticProps`
- NEIMPORTUJ z `@shadcn/ui` (neexistuje!)
- NEPOUŽÍVAJ hardcoded farby (`bg-red-500`)
- NEPOUŽÍVAJ `axios` - použi natívny `fetch`

## Štruktúra komponentov:
```
src/
├── app/                    # App Router pages
│   ├── (auth)/            # Route groups
│   ├── dashboard/
│   └── api/               # Len pre webhooky
├── components/
│   ├── ui/                # Shadcn komponenty
│   └── [feature]/         # Feature komponenty
├── lib/
│   ├── db/                # Drizzle schema + queries
│   └── utils.ts           # cn() helper
└── actions/               # Server Actions
```

✅ Direktívy

Imperatívne príkazy namiesto opisov

📌 Verzie

"Next.js 15" nie len "Next.js"

🚫 Negatívne

Čo NIKDY nerobiť

🪝 Hooks — Automatizácia

Hooks sa spúšťajú automaticky pri udalostiach (editácia súboru, spustenie príkazu). Zabezpečujú kvalitu bez manuálnej kontroly.

settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/typescript-check.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation.sh"
          }
        ]
      }
    ]
  }
}

typescript-check.sh

#!/bin/bash
# Spustí sa po každej editácii

echo "🔍 Running TypeScript check..."
npx tsc --noEmit

if [ $? -ne 0 ]; then
    echo "❌ TypeScript errors found"
    exit 1
fi

echo "✅ TypeScript OK"

validate-components.sh

#!/bin/bash
# Kontroluje Shadcn anti-vzory

# Hľadaj nesprávne importy
if grep -r "@shadcn/ui" src/; then
    echo "❌ Nesprávny import!"
    echo "Použi: @/components/ui"
    exit 1
fi

# Hľadaj hardcoded farby
if grep -rE "bg-(red|blue|green)-[0-9]" src/; then
    echo "⚠️ Použi sémantické tokeny"
fi

🔄 Workflows

Workflow: Generovanie Shadcn Komponentu

1

Používateľ zadá prompt

"Vytvor kartu profilu používateľa s avatarom a tlačidlom na odhlásenie."

2

Hook: UserPromptSubmit

Detekuje kľúčové slová "komponent", "karta", "avatar". Skontroluje či existujú components/ui/card.tsx a components/ui/avatar.tsx.

3

Agent: Exekúcia

# Ak komponenty chýbajú
npx shadcn@latest add card avatar button

# Agent prečíta lokálne verzie
# a vygeneruje UserProfileCard.tsx

4

Hook: PostToolUse

Spustí validate-components.sh — kontroluje anti-vzory, správne importy, sémantické tokeny.

✅ Dobré vzory

// Správny import
import { Card } from "@/components/ui/card"

// Sémantické farby
<Button variant="destructive">
  Odstrániť
</Button>

// Server Component (default)
export default async function Page() {
  const data = await fetchData()
  return <Card>{data}</Card>
}

❌ Anti-vzory

// ❌ Nesprávny import
import { Card } from "@shadcn/ui"

// ❌ Hardcoded farby
<button className="bg-red-500">
  Odstrániť
</button>

// ❌ API route namiesto Server Action
// pages/api/users.ts
export default function handler(req, res) {
  // ...
}

📚 Zdroje

📦

claude-config-composer

546 ⭐ • NPM balík

Inteligentné zlučovanie konfigurácií. Production-ready s 124 testami.

🎯

claude-nextjs-skills

18 ⭐ • Eval-tested

Skills zlepšili Vercel eval score z 32% na 78%.

🔥

claude-code-infrastructure-showcase

7.6k ⭐ • Production-tested

Auto-aktivácia skills, hooks systém, dev docs pattern.

📋

awesome-claude-skills

Kuratovaný zoznam

Zbierka skills pre rôzne technológie a use-cases.