Entwicklung von Next.js-Seiten und -Routen (nextjs-page-dev)
Spezialisierter Workflow zum Erstellen production-ready Next.js App Router-Seiten mit asynchronen Routenparametern, lokalisierten Übersetzungswörterbüchern, dynamischen Metadaten, typsicheren JSON-LD-Strukturierten Daten (schema-dts) und statischer Vorab-Generierung.
[!TIP] Modulare Assets & Vertiefungshandbücher:
- Streaming & UI-Grenzen:
references/streaming-and-boundaries.md- Seitenkonventionen & Lebenszyklus:
references/page-conventions-and-lifecycle.md- SEO & Leitfaden zu Strukturierten Daten:
references/seo-structured-data-guide.md- Wiederverwendbare Vorlagen:
resources/templates/- Verifikationsskript:
scripts/verify-page.ps1(Windows) /scripts/verify-page.sh(Linux)
Architekturregeln und Standards
1. Planungskontext & Routen-Registry
- Lies
docs/project.json, umsupported_languages,dictionaries_dir(Standard:"messages") undnew_component_dirzu ermitteln. - Alle Navigations-URLs MÜSSEN auf
ROUTESaus@/lib/routesoder@/i18n/navigationverweisen. - Zielpfad-Hierarchie der Seite:
app/[locale]/<route-path>/page.tsx(oderapp/<route-path>/page.tsxfür nicht-lokalisierte Seiten).
2. Keine hartcodierten Texte & Befüllung der Wörterbücher
- Keine hartcodierten Texte: Seitenüberschriften, Titel, Beschreibungen und statische Labels MÜSSEN vor dem Schreiben von JSX in
messages/[locale].jsonfür allesupported_languageshinzugefügt werden. - RSC-Übersetzungen: Lies Übersetzungen in Server-Komponenten mit
await getTranslations('<namespace>').
3. SEO, Metadaten & JSON-LD
- Dynamische Metadaten: Exportiere
generateMetadata({ params, searchParams }: Props), das dynamischentitle,descriptionund kanonische URL (alternates: { canonical: ... }) bereitstellt. - Strukturierte Daten: Injiziere typisierte JSON-LD mit
schema-dts(WithContext<T>), eingewickelt in<script type="application/ld+json">, wobei<-Zeichen als\u003cescaped werden. - Konsultiere
references/seo-structured-data-guide.mdfür Schemata.
4. Statische Vorab-Generierung (generateStaticParams)
- Wenn die Seite unter einem dynamischen Segment
[locale](oder einem anderen dynamischen Segment) verschachtelt ist undsupported_languagesmehr als eine Sprache enthält, exportieregenerateStaticParams(), das{ locale }für alle unterstützten Sprachen zurückgibt.
5. Sofortnavigation & Granulares Suspense-Herunterschieben
- Granulare Ladezustände: Schiebe
<Suspense>nach unten zu spezifischen dynamischen Unterkomponenten, sodass statische/zwischengespeicherte Abschnitte (Header, Hero, zwischengespeicherte Produktinfo) sofort in die Statische Shell und App Shell gehoben werden. - Opt-Out: Wenn ein Segment inhärent dynamisch ist und keine Sofortrückmeldung gewünscht wird, konfiguriere
export const instant = false. - Konsultiere
references/streaming-and-boundaries.mdfür Streaming-Muster.
Workflow-Schritte
-
Schritt 0: Implementierungsplanung & Genehmigungshürde
- Lies
docs/project.jsonund die Zielroutendefinition inlib/routes.ts. - Formuliere Seitenmetadaten, JSON-LD-Schema-Typ, Übersetzungs-Namespaces und Komponenten-Layout.
- Lege dem Benutzer einen prägnanten Implementierungsplan vor, falls größere neue Seiten erstellt werden.
- Lies
-
Schritt 1: Übersetzungswörterbücher befüllen
- Füge Seitentitel, Meta-Beschreibung und Seitenkörpertext in allen Locale-Dateien (
messages/en.json,messages/fa.jsonusw.) unter einem eigenen Seiten-Namespace hinzu.
- Füge Seitentitel, Meta-Beschreibung und Seitenkörpertext in allen Locale-Dateien (
-
Schritt 2: Begleit-Skelette erstellen (
loading.tsx)- Falls die Seite Inhalte streamt oder Daten abruft, setze
loading.tsxbasierend auf loading.tsx.template ein.
- Falls die Seite Inhalte streamt oder Daten abruft, setze
-
Schritt 3: Seitenkomponente implementieren (
page.tsx)- Setze page.tsx.template ein und passe es an:
- Definiere das asynchrone Props-Interface (
params: Promise<{ locale: string, ... }>,searchParams). - Exportiere
generateMetadata(), das dynamische Titel und kanonische Alternativen auflöst. - Exportiere
generateStaticParams()für lokalisierte/dynamische Routen. - Implementiere die RSC-Seite, die Abschnittskomponenten aus
<new_component_dir>/<page-name>/zusammensetzt. - Rendere die
<JsonLd>-Komponente für strukturierte Daten.
- Definiere das asynchrone Props-Interface (
- Setze page.tsx.template ein und passe es an:
-
Schritt 4: Verifikation & Plausibilitätsprüfung
- Führe das Seitenverifikationsskript aus:
- Windows (PowerShell):
pwsh .agents/skills/nextjs-page-dev/scripts/verify-page.ps1 -RoutePath <route_dir> - Linux / macOS (Bash):
bash .agents/skills/nextjs-page-dev/scripts/verify-page.sh <route_dir>
- Windows (PowerShell):
- Stelle sicher, dass keine TypeScript-Fehler oder fehlende Wörterbuchfehler auftreten.
- Führe das Seitenverifikationsskript aus:
-
Schritt 5: Checkliste Implementierungsplan synchronisieren
- Hake die abgeschlossenen Seiteninfrastruktur-Elemente (
page.tsx,loading.tsx,error.tsx,generateMetadata,JSON-LD Schema,generateStaticParams()) indocs/plan/05-pages-and-components.mdab. - Wenn alle Unterchecklisten für die Komponenten und alle Seiteninfrastruktur-Aufgaben für diese Seite abgeschlossen sind, hake das übergeordnete Seiten-Element ab (
- [x]).
- Hake die abgeschlossenen Seiteninfrastruktur-Elemente (