Priorität: P0 (KRITISCH)
Implementierungsrichtlinien
Routing-Architektur
- Struktur: Verwenden Sie das
app/-Verzeichnis. Definieren Sie Routen mit app/dashboard/layout.tsx, das {children} zurückgibt; gemeinsame UI wird automatisch in app/layout.tsx verschachtelt. Behandeln Sie Zustände mit loading.tsx, error.tsx und not-found.tsx.
- Segmente: Organisieren Sie Funktionen mit Route Groups (Klammern
(auth)), die aus dem URL-Pfad ausgeschlossen werden. Verwenden Sie Dynamic Routes (Klammern [slug]) und definieren Sie statische Pfade über generateStaticParams.
- Spezialisiert: Verwenden Sie Parallel Routes (
@modal), indem Sie den Slot zum übergeordneten Layout hinzufügen und einen default.tsx-Fallback bereitstellen. Verwenden Sie Intercepting Routes ((.)route) für erweiterte Layouts wie Dashboards.
Daten & Funktionen
- Next.js 15+ Async: Verwenden Sie immer
await für params: Promise, searchParams, cookies() und headers().
- Sicherheit: Verwenden Sie
middleware.ts für serverseitige Authentifizierung und Weiterleitungen. Stellen Sie sicher, dass alle Route Handlers (route.ts) mit entsprechenden Authentifizierungsprüfungen gesichert sind.
- RSC: Standardmäßig React Server Components (RSC). Verwenden Sie
'use client' nur an Blattknoten für Interaktivität (Hooks/Events).
- Fehlergrenzen: Erstellen Sie
app/dashboard/loading.tsx, um Routen automatisch in eine Suspense-Grenze zu verpacken. In error.tsx verwenden Sie 'use client' und stellen Sie eine reset: () => void-Funktion bereit.
const theme = cookieStore.get('theme');
## Dateikonventionen
- **page.tsx**: UI für eine Route.
- **layout.tsx**: Gemeinsame UI, die Kinder umschließt. Besteht über Navigation hinweg.
- **loading.tsx**: Suspense-Grenze für Ladezustände.
- **error.tsx**: Fehlergrenze (Muss eine Client-Komponente sein).
- **route.ts**: Serverseitiger API-Endpunkt.
## Strukturmuster
- **Route Groups**: Verwenden Sie Klammern `(auth)`, um zu organisieren, ohne den URL-Pfad zu beeinflussen.
- **Private Ordner**: Verwenden Sie Unterstrich `_lib`, um vom Routing auszuschließen.
- **Dynamische Routen**: Verwenden Sie Klammern `[slug]` oder `[...slug]` (Catch-all).
## Best Practices
- **RSC-Grenzen**: Stellen Sie sicher, dass Props, die an Client-Komponenten übergeben werden, serialisierbar sind. Siehe [RSC-Grenzen & Serialisierung](../architecture/references/RSC_BOUNDARIES.md).
- **Parallel Routes (`@folder`)**: Rendern Sie mehrere Seiten im selben Layout. Verwenden Sie `default.tsx` für Fallbacks.
- **Intercepting Routes (`(..)folder`)**: Laden Sie Routen im aktuellen Layout-Kontext.
- **Kolokation**: Halten Sie Komponentendateien, Stile und Tests im Routenordner.
- **Layouts**: Verwenden Sie das Root-Layout (`app/layout.tsx`) für `<html>`- und `<body>`-Tags.
- [**Self-Hosting-Standard**](references/SELF_HOSTING.md)
## Anti-Patterns
- **Keine ungewarteten async APIs**: `params`, `cookies()`, `headers()` sind in Next.js 15+ Promises; immer `await` verwenden.
- **Kein `'use client'` an der Baumwurzel**: Platzieren Sie es an Blättern; halten Sie Layouts und Seiten als Server-Komponenten.
- **Kein `<html>`/`<body>` in verschachtelten Layouts**: Nur `app/layout.tsx` (Root-Layout) sollte diese enthalten.
- **Keine fehlende `error.tsx`**: Jedes Routensegment benötigt eine Client-Komponenten-Fehlergrenze.