Next.js App Router Experte

Next.js Best Practices

Wenden Sie diese Regeln beim Schreiben oder Überprüfen von Next.js-Code an.

Dateikonventionen

Siehe file-conventions.md für:

• Projektstruktur und spezielle Dateien
• Routensegmente (dynamisch, Catch-All, Gruppen)
• Parallele und abfangende Routen
• Middleware-Umbenennung in v16 (middleware → proxy)

RSC-Grenzen

Erkennen ungültiger Muster in React Server Components.

Siehe rsc-boundaries.md für:

• Erkennung asynchroner Client-Komponenten (ungültig)
• Erkennung nicht serialisierbarer Props
• Ausnahmen bei Server-Aktionen

Asynchrone Muster

Next.js 15+ Änderungen bei asynchronen APIs.

Siehe async-patterns.md für:

• Asynchrone params und searchParams
• Asynchrone cookies() und headers()
• Migrations-Codemod

Laufzeitauswahl

Siehe runtime-selection.md für:

• Standardmäßig Node.js-Laufzeit verwenden
• Wann die Edge-Laufzeit geeignet ist

Direktiven

Siehe directives.md für:

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

Funktionen

Siehe functions.md für:

• Navigations-Hooks: useRouter, usePathname, useSearchParams, useParams
• Server-Funktionen: cookies, headers, draftMode, after
• Generate-Funktionen: generateStaticParams, generateMetadata

Fehlerbehandlung

Siehe error-handling.md für:

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized (Authentifizierungsfehler)
• unstable_rethrow für Catch-Blöcke

Datenmuster

Siehe data-patterns.md für:

• Server-Komponenten vs. Server-Aktionen vs. Routen-Handler
• Vermeidung von Daten-Waterfalls (Promise.all, Suspense, preload)
• Datenabruf in Client-Komponenten

Routen-Handler

Siehe route-handlers.md für:

• Grundlagen von route.ts
• Konflikte zwischen GET-Handler und page.tsx
• Umgebungsverhalten (kein React DOM)
• Wann man sie statt Server-Aktionen verwendet

Metadaten & OG-Bilder

Siehe metadata.md für:

• Statische und dynamische Metadaten
• generateMetadata-Funktion
• OG-Bildgenerierung mit next/og
• Dateibasierte Metadaten-Konventionen

Bildoptimierung

Siehe image.md für:

• Immer next/image anstelle von <img> verwenden
• Konfiguration entfernter Bilder
• Responsives sizes-Attribut
• Unschärfe-Platzhalter
• Priority Loading für LCP

Schriftoptimierung

Siehe font.md für:

• next/font-Einrichtung
• Google Fonts, lokale Schriften
• Tailwind CSS-Integration
• Vorladen von Teilmengen

Bundling

Siehe bundling.md für:

• Nicht serverkompatible Pakete
• CSS-Importe (keine Link-Tags)
• Polyfills (bereits enthalten)
• ESM/CommonJS-Probleme
• Bundle-Analyse

Skripte

Siehe scripts.md für:

• next/script vs. native Script-Tags
• Inline-Skripte benötigen id
• Ladestrategien
• Google Analytics mit @next/third-parties

Hydratationsfehler

Siehe hydration-error.md für:

• Häufige Ursachen (Browser-APIs, Daten, ungültiges HTML)
• Debugging mit der Fehlerüberlagerung
• Korrekturen für jede Ursache

Suspense-Grenzen

Siehe suspense-boundaries.md für:

• CSR-Bailout mit useSearchParams und usePathname
• Welche Hooks Suspense-Grenzen erfordern

Parallele und abfangende Routen

Siehe parallel-routes.md für:

• Modal-Muster mit @slot und (.)-Abfangmechanismen
• default.tsx für Ausweichlösungen
• Korrektes Schließen von Modalen mit router.back()

Self-Hosting

Siehe self-hosting.md für:

• output: 'standalone' für Docker
• Cache-Handler für Multi-Instanz-ISR
• Was funktioniert und was zusätzliche Einrichtung erfordert

Debug-Tricks

Siehe debug-tricks.md für:

• MCP-Endpunkt für KI-gestütztes Debugging
• Neuerstellen bestimmter Routen mit --debug-build-paths