Next.js 15 + App Router Specialist
Vollständige Next.js 15-Referenz für die Quetrex-Entwicklung.
Diese Fähigkeit bietet umfassende Anleitungen zu allen Next.js 15 App Router-Mustern und stellt sicher, dass Agenten modernes Next.js korrekt implementieren.
KRITISCHE REGELN (NIEMALS VERLETZEN)
Diese Regeln sind NICHT VERHANDELBAR. Verstöße führen zu Build-Fehlern.
1. IMMER <Image> von next/image verwenden – NIEMALS <img>
// ✅ IMMER SO MACHEN
import Image from 'next/image'
<Image src="/logo.png" alt="Logo" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />
// ❌ NIEMALS SO MACHEN – BUILD WIRD FEHLSCHLAGEN
<img src="/logo.png" alt="Logo" />
<img src={user.avatar} alt={user.name} />
Warum: Die Next.js Image-Komponente bietet automatische Optimierung, Lazy Loading und verhindert Layout-Verschiebungen. ESLint ist so konfiguriert, dass es bei Verwendung von <img> einen Build-Fehler ausgibt.
2. Server Components sind STANDARD – nur "use client" hinzufügen, wenn nötig
3. Niemals asynchrone Client-Komponenten erstellen
4. Immer eine Cache-Strategie für fetch() angeben
Wann diese Fähigkeit verwenden
Verwenden Sie diese Fähigkeit, wenn Sie arbeiten mit:
- Erstellen neuer Routen oder Seiten
- Implementieren von Datenabruf (Server Components vs Client Components)
- Entscheidungen zwischen Server- und Client-Komponenten
- Server Actions und Formularverarbeitung
- Streaming und Suspense
- Metadaten und SEO
- Route Handlers (API-Routen)
- Caching-Strategien
- Leistungsoptimierung
Vollständige Dokumentation
Diese Fähigkeit enthält umfassende Anleitungen, die jedes Next.js 15-Muster abdecken:
📁 App Router Complete Guide
45+ Beispiele zu:
- Dateibasierte Routen (page.tsx, layout.tsx, route.ts)
- Dynamische Routen ([id], [...slug], [[...slug]])
- Routengruppen ((group))
- Private Ordner (_folder)
- Route Handlers (API-Routen)
- Layouts und Templates
- Lade-UI (loading.tsx)
- Fehlergrenzen (error.tsx, global-error.tsx)
- Not-found-Seiten (not-found.tsx)
- Parallele Routen (@folder)
- Abfangende Routen ((.)folder)
- Routensegment-Konfiguration (dynamic, revalidate, runtime)
🔄 Data Fetching Complete Guide
35+ Beispiele zu:
- Server Component Datenabruf (async/await)
- Client Component Datenabruf (useEffect, React Query, SWR)
- Paralleler Datenabruf (Promise.all)
- Sequenzieller Datenabruf (Wasserfall-Vermeidung)
- Streaming-Daten (Suspense-Grenzen)
- Server-Sent Events (SSE für Quetrex Voice)
- Datenmutationen (Server Actions)
- Optimistische Aktualisierungen (useOptimistic)
- Formularverarbeitung (useFormStatus, useActionState)
- Request-Deduplizierung
- Vorabladen von Daten
💾 Caching Strategies Guide
35+ Beispiele zu:
- Request Memoization (automatische Deduplizierung)
- Data Cache (fetch-Cache-Verhalten)
- Full Route Cache (statisch vs dynamisch)
- Router Cache (clientseitiger Cache)
- Cache-Konfiguration (force-cache, no-store, revalidate)
- Cache-Tags (revalidateTag, revalidatePath)
- On-demand Revalidierung
- Zeitbasierte Revalidierung (ISR)
- Cache-Debugging-Techniken
- Cache deaktivieren
⚡ Server Actions Complete Guide
31+ Beispiele zu:
- Grundlegende Server Action-Muster
- Formularaktionen (progressive Enhancement)
- Schaltflächenaktionen (programmatische Aufrufe)
- useFormStatus-Hook (Ladezustände)
- useActionState-Hook (Zustandsverwaltung)
- useOptimistic-Hook (optimistische UI)
- Fehlerbehandlung in Aktionen
- Validierung mit Zod
- Rückgabe von JSON vs Redirect
- Sicherheit (Authentifizierung, CSRF)
- Rate Limiting
- Datenbanktransaktionen
🎯 Metadata API Guide
26+ Beispiele zu:
- Statische Metadaten (exportiertes Objekt)
- Dynamische Metadaten (generateMetadata)
- Dateibasierte Metadaten (icon.png, opengraph-image.png)
- Open Graph-Metadaten
- Twitter Cards
- JSON-LD strukturierte Daten
- Viewport-Konfiguration
- PWA-Manifest
- Robots.txt
- Sitemap-Generierung
✅ Pattern Validator
Ausführbares Python-Skript, das prüft:
- Server Components verwenden keine Client-only-APIs
- Client Components haben die Direktive "use client"
- Datenabruf verwendet die richtige Cache-Strategie
- Server Actions sind mit "use server" markiert
- Metadata API wird korrekt verwendet
- Bildoptimierung ( nicht )
- Dynamische Importe für schwere Komponenten
Ausführen mit: python validate-patterns.py /pfad/zu/src
Kurzreferenz
Entscheidungsbaum: Server vs Client Components
Benötigen Sie Interaktivität (onClick, onChange, etc.)?
├─ JA → Client Component ("use client")
└─ NEIN → Server Component (Standard)
Benötigen Sie React Hooks (useState, useEffect)?
├─ JA → Client Component
└─ NEIN → Server Component
Benötigen Sie Browser-APIs (window, localStorage)?
├─ JA → Client Component
└─ NEIN → Server Component
Müssen Sie Daten abrufen?
├─ Server Component verwenden (bevorzugt)
└─ Client Component nur, wenn Daten clientseitig sein müssen
Ist die Komponente rein präsentativ?
└─ Server Component (bessere Leistung)
Häufige Muster
1. Datenabruf in Server Component
// app/projects/page.tsx
export default async function ProjectsPage() {
const projects = await db.project.findMany()
return <ProjectList projects={projects} />
}
2. Client Component mit Interaktivität
// components/ProjectCard.tsx
'use client'
import { useState } from 'react'
export function ProjectCard({ project }: Props) {
const [loading, setLoading] = useState(false)
const handleDelete = async () => {
setLoading(true)
await deleteProject(project.id)
setLoading(false)
}
return (
<div>
<h2>{project.name}</h2>
<button onClick={handleDelete} disabled={loading}>
Löschen
</button>
</div>
)
}
3. Server Action mit Formular
// app/actions.ts
'use server'
export async function createProject(formData: FormData) {
const name = formData.get('name') as string
const project = await db.project.create({ data: { name } })
revalidatePath('/projects')
return { success: true, project }
}
// app/projects/new/page.tsx
import { createProject } from '@/app/actions'
export default function NewProjectPage() {
return (
<form action={createProject}>
<input name="name" required />
<button type="submit">Erstellen</button>
</form>
)
}
4. Streaming mit Suspense
// app/dashboard/page.tsx
import { Suspense } from 'react'
export default function DashboardPage() {
return (
<div>
<Suspense fallback={<ProjectsSkeleton />}>
<ProjectsAsync />
</Suspense>
<Suspense fallback={<UsersSkeleton />}>
<UsersAsync />
</Suspense>
</div>
)
}
async function ProjectsAsync() {
const projects = await fetchProjects() // Langsame Abfrage
return <ProjectList projects={projects} />
}
5. Dynamische Metadaten
// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'
export async function generateMetadata({
params,
}: {
params: Promise<{ slug: string }>
}): Promise<Metadata> {
const { slug } = await params
const post = await fetchPost(slug)
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [post.coverImage],
},
}
}
Best Practices für Quetrex
1. Standardmäßig Server Components verwenden
// ✅ RICHTIG: Server Component (Standard)
export default async function ProjectsPage() {
const projects = await fetchProjects()
return <ProjectList projects={projects} />
}
// ❌ FALSCH: Client Component, wenn nicht nötig
'use client'
export default function ProjectsPage() {
const [projects, setProjects] = useState([])
useEffect(() => {
fetchProjects().then(setProjects)
}, [])
return <ProjectList projects={projects} />
}
2. Korrekte Cache-Strategie verwenden
// Statischer Inhalt (unbegrenzt gecacht)
const categories = await fetch('https://api.example.com/categories', {
cache: 'force-cache',
}).then(r => r.json())
// Dynamischer Inhalt (kein Cache)
const user = await fetch('https://api.example.com/me', {
cache: 'no-store',
}).then(r => r.json())
// ISR (stündliche Revalidierung)
const products = await fetch('https://api.example.com/products', {
next: { revalidate: 3600 },
}).then(r => r.json())
3. Korrekte Fehlergrenzen implementieren
// app/dashboard/error.tsx
'use client'
export default function DashboardError({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>Etwas ist schiefgelaufen!</h2>
<button onClick={reset}>Erneut versuchen</button>
</div>
)
}
4. Ladezustände verwenden
// app/dashboard/loading.tsx
export default function DashboardLoading() {
return <DashboardSkeleton />
}
5. Bilder optimieren
// ✅ RICHTIG: next/image verwenden
import Image from 'next/image'
export function ProjectCard({ project }) {
return (
<Image
src={project.image}
alt={project.name}
width={400}
height={300}
/>
)
}
// ❌ FALSCH: <img>-Tag verwenden
export function ProjectCard({ project }) {
return <img src={project.image} alt={project.name} />
}
Häufige Fehler vermeiden
❌ Fehler 1: Asynchrone Client Component
// ❌ FALSCH: Dies ist ein Syntaxfehler
'use client'
export default async function BadComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
// ✅ RICHTIG: Server Component oder useEffect verwenden
export default async function GoodComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
❌ Fehler 2: Client-APIs in Server Component
// ❌ FALSCH: Server Components können keine Browser-APIs verwenden
export default function BadComponent() {
const [state, setState] = useState(false) // Fehler!
return <div>{state}</div>
}
// ✅ RICHTIG: "use client"-Direktive hinzufügen
'use client'
export default function GoodComponent() {
const [state, setState] = useState(false)
return <div>{state}</div>
}
❌ Fehler 3: Fehlende Cache-Strategie
// ❌ FALSCH: Unklares Caching-Verhalten
const data = await fetch('/api/data')
// ✅ RICHTIG: Explizite Cache-Strategie
const data = await fetch('/api/data', {
cache: 'no-store', // oder 'force-cache', oder { next: { revalidate: 60 } }
})
❌ Fehler 4: Kein verwenden
// ❌ FALSCH: Nicht optimierte Bilder
<img src="/logo.png" alt="Logo" />
// ✅ RICHTIG: Next.js Bildoptimierung verwenden
<Image src="/logo.png" alt="Logo" width={200} height={100} />
Fehlerbehebung
Fehler: "You're importing a component that needs useState..."
Lösung: Fügen Sie 'use client' zur Komponentendatei hinzu.
Fehler: "async/await is not valid in Client Components"
Lösung: Entfernen Sie 'use client' oder verwenden Sie useEffect anstelle einer asynchronen Komponente.
Fehler: "process is not defined"
Lösung: Umgebungsvariablen in Client Components benötigen das Präfix NEXT_PUBLIC_.
Fehler: "Headers already sent"
Lösung: Verwenden Sie headers() oder cookies() nicht, nachdem die Antwort gesendet wurde. Rufen Sie sie vor jeglichem Streaming auf.
Offizielle Dokumentation
- Next.js 15.5 Docs: https://nextjs.org/docs
- App Router: https://nextjs.org/docs/app
- Data Fetching: https://nextjs.org/docs/app/building-your-application/data-fetching
- Server Actions: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
- Caching: https://nextjs.org/docs/app/building-your-application/caching
- Metadata: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
- Examples: https://github.com/vercel/next.js/tree/canary/examples
Validierung
Führen Sie den Muster-Validator aus, um Ihren Code zu prüfen:
python .claude/skills/nextjs-15-specialist/validate-patterns.py src/
Der Validator prüft:
- ✅ Asynchrone Client Components (verboten)
- ✅ Client-APIs in Server Components
- ✅ "use client"-Direktive Platzierung
- ✅ Server Action asynchrone Funktionen
- ✅ Bildoptimierung
- ✅ Metadaten in dynamischen Routen
- ✅ Dynamische Importe für schwere Komponenten
- ✅ Fetch-Cache-Strategien
- ✅ Routensegment-Konfiguration
Zusammenfassung
Diese Fähigkeit stellt sicher, dass Sie:
- Den korrekten Komponententyp wählen (Server vs Client)
- Korrekte Datenabrufmuster implementieren
- Angemessene Caching-Strategien verwenden
- Server Actions richtig handhaben
- Metadaten und SEO optimieren
- Häufige Next.js-Fehler vermeiden
- Den Architekturrichtlinien von Quetrex folgen
Bei Unsicherheit:
- Lesen Sie die spezifische Anleitung (Links oben)
- Führen Sie den Validator aus
- Prüfen Sie die offiziellen Next.js 15-Dokumentationen
- Verwenden Sie standardmäßig Server Components
Zuletzt aktualisiert: 2025-11-23 Next.js Version: 15.5 Gesamtbeispiele: 150+ Gesamtzeilen: 4.000+
