BIGboss248/nextjs-wordpress

Next.js Komponenten- & Skelettentwicklung (nextjs-component-dev)

Spezialisierter Workflow zur Erstellung produktionsreifer React-Server-Komponenten (RSC) und Client-Komponenten mit Suspense-Skeletten, dualem TDD-Testing (Jest + RTL Unit-Tests und Playwright-Integration/Hydrierung/visuelle Checks), next-intl-Wörterbuch-gestützten Übersetzungen, semantischen Theme-Tokens und Live-Runtime-Diagnose über next-devtools MCP.

[!TIP] Modulare Assets & Vorlagen:

• Next.js Docs Suche & Kontext: references/nextjs-docs-lookup.md
• Testarchitektur & Verifikation: references/testing-architecture-guide.md
• Storybook-Standards & Trennung: references/storybook-reference.md
• Sofortnavigation & Vorabruf: references/instant-navigation-and-prefetching.md
• Next DevTools Debugging-Anleitung: references/next-devtools-debugging.md
• Caching & Revalidierung: references/caching-and-revalidation.md
• Code-Vorlagen: resources/templates/ (Komponente, Skelett, Jest Unit-Test, Playwright Spec)
• Referenzimplementierungen: examples/
• Verifikationsskripte: scripts/verify-dev.ps1 (Windows) / scripts/verify-dev.sh (Linux)

---

Architekturregeln & Standards

1. Planungskontext & Pfade

• Lies docs/project.json, um package_manager, new_component_dir, style_file_dir, component_library, dictionaries_dir (Standard: "messages") und supported_languages zu ermitteln.
• Alle internen Routen MÜSSEN ROUTES aus @/lib/routes verwenden.
• Alle Autoren-/Site-Metadaten MÜSSEN SITE_CONFIG aus @/lib/site-config verwenden.
• Zielpfad-Hierarchie: <new_component_dir>/<page_or_global>/<ComponentName>/
  • Kategorie: global/ für geteilte Layout-Chrome; <page-name>/ (z.B. home/, about/, lab/) für seitenbezogene Abschnitte.

2. Next.js Interne Docs-Suche (node_modules/next/dist/docs)

• Lokale Docs über Codebase Memory MCP durchsuchen: Bei jeder Komponentenerstellung die lokalen Next.js-Distributionsdocs unter node_modules/next/dist/docs/ aktiv über codebase-memory MCP-Tools (search_code, search_graph, get_code_snippet) abfragen und nach relevanten API-Signaturen, Direktiven ('use cache', 'use client', 'use server'), eingebauten Komponenten (next/image, next/link, next/font, <Form>), Navigations-Hooks (useRouter, usePathname) und Caching-Richtlinien (cacheLife, cacheTag) suchen.
• Veraltungen & Halluzinationen eliminieren: Niemals auf Annahmen oder veraltete Next.js-Muster verlassen; die lokalen node_modules/next/dist/docs, die der installierten Paketversion entsprechen, sind die primäre Informationsquelle. Konsultiere references/nextjs-docs-lookup.md.

3. Dev-Server & Next DevTools-Protokoll

• Dev-Server Prüfung & Einschalten: Vor/während der Komponentenentwicklung prüfen, ob der Next.js Dev-Server über den next-devtools MCP-Server (nextjs_index) läuft.
• Wenn Server läuft: Sofort in den laufenden Server und Port einklinken; nicht neu starten.
• Wenn Server nicht läuft: Den Dev-Server im Hintergrund starten (pnpm dev, IsDaemon: true) und die Verbindung über nextjs_index verifizieren.
• Runtime-Debugging: Nach der Implementierung von Komponenten next-devtools (nextjs_call) abfragen, um Fehler zu inspizieren, den Build-Status zu überprüfen und Runtime-Probleme sofort zu diagnostizieren. Konsultiere references/next-devtools-debugging.md.

4. RSC-Grenzen & Client Leaf Push-Down

1. Server-Komponenten standardmäßig: Komponenten serverseitig rendern (async function).
2. "use client" nach unten schieben: Interaktive Handler (Buttons, Toggles, Formulareingaben) in kleine Client Leaf-Komponenten isolieren.
3. RSC-Komposition: Server-Komponenten als children oder Props an Client-Wrapper übergeben. Niemals Server-Komponenten innerhalb von "use client"-Dateien importieren.

5. Styling, Logische Eigenschaften & Theme-Tokens

• Semantische Tokens: Ausschließlich semantische CSS-Variablen verwenden, die in app/globals.css definiert sind (bg-background, text-foreground, border-border, text-muted-foreground). Hartcodierte Hex-Farben (#FAFAFA) oder rohe Farbskalen (bg-blue-500) sind VERBOTEN.
• Klassenzusammenführung: Klassen immer mit cn(...) (clsx + tailwind-merge) zusammenführen.
• Logische Eigenschaften (BiDi): Ausschließlich Tailwind-logische Eigenschaften verwenden (ms-, pe-, ps-, me-, start, end). Physische Richtungsklassen (ml-, mr-, pl-, pr-, left-, right-) sind VERBOTEN.
• Fortschrittslinks: <Link> aus @vercel/react-transition-progress für die primäre Navigation, Hero-CTA und interaktive Karten verwenden; standard next/link für statische Utility-Links.
• Bilder: Immer next/image mit expliziten Abmessungen oder fill, responsiven sizes und priority für Above-the-Fold-LCP-Assets verwenden.

6. Sofortnavigation, Granulares Suspense & Caching-Architektur

• Die drei Hebel für Sofort-Komponenten:
  1. Nach unten schieben: Anfragespezifische asynchrone Operationen (await params, await searchParams, cookies(), headers(), ungecachte DB/API-Aufrufe) in Sub-Komponenten extrahieren, die in <Suspense> eingewickelt sind. Statische Eltern und Geschwister heben direkt in die statische/App Shell.
  2. Cache: 'use cache' mit cacheLife und cacheTag auf Funktions-/Komponentenebene paaren. Session-Bridging-Muster verwenden:
     • Muster A (Extrahieren & Übergeben): Session-Attribute (z.B. team_id, role, tier) aus cookies() außerhalb extrahieren und als Argumente an 'use cache'-Funktionen übergeben, sodass zwischengespeicherte Daten von allen Benutzern mit übereinstimmenden Attributen geteilt werden (Kosten skalieren mit Team/Attribut-Anzahl, nicht mit der Anzahl der Benutzersitzungen).
     • Muster B ("use cache: private"): Für streng benutzerspezifische Session-Suchen nur browserseitiges Session-Caching mit stale >= 5m verwenden, das mit der App Shell reist.
  3. Vorabrufstrategie & Dichte Gitter:
     • Standard App Shell Vorabruf (<Link> / prefetch={null}): Ruft eine gemeinsame statische/App Shell pro Route vorab ab. Begrenzte Kosten ($O(\text{routes})$), null Server-Aufrufe pro Link. Verwenden für dichte Feeds, Kartengitter (50+ Karten) und Bulk-Navigation.
     • Pro-Link Vorabruf (<Link prefetch={true}>): Löst dynamische URL-Daten (params, searchParams) vor der Navigation mit 1 Server-Aufruf pro sichtbarem Link auf. Sparsam verwenden für High-Intent primäre CTAs, Hero-Aktionen oder Master-Detail-Listenelemente, bei denen Skelett-Flackern vermieden werden muss.
     • Dichte Kartengitter: NIEMALS pauschal prefetch={true} über Dutzende von Karten in Feeds verwenden. Standard-<Link> beibehalten oder Hover/Focus-Intent-Vorabruf (router.prefetch()) verwenden.
• Granulare Ladestatus (Anti-Vollbild-Flash): Niemals eine gesamte Komponente oder Seite in eine einzige top-level <Suspense>-Grenze einwickeln, die vollständige Skelette aufblinkt. Titel, Layout-Rahmen und zwischengespeicherte Inhalte sofort sichtbar halten; <Suspense> streng um dynamische Streaming-Slots platzieren.
• Native Next.js 16 Caching-Direktiven: Konsultiere references/instant-navigation-and-prefetching.md und references/caching-and-revalidation.md.

7. TanStack Query & Server-Vorabruf

• Einheitlicher Cache-Vertrag: Definiere key, tag und queryOptions mit explizitem staleTime (z.B. 30_000 ms).
• Server-Vorabruf: Unerwarteten Vorabruf auslösen (void queryClient.prefetchQuery(...)) und interne DB-Funktionen direkt aufrufen (null relativer Fetch auf dem Server). Mit <HydrationBoundary> dehydrieren.
• Gestreamte Komponenten: useSuspenseQuery innerhalb von <Suspense fallback={<[ComponentName]Skeleton />}> verwenden.
• Optimistische Mutationen: useMutation mit onMutate-Cache-Snapshots und onError-Rollbacks verwenden; Server-Aktionen mit updateTag(cache.tag) aufrufen.

8. Dual-Layer Testaufteilung (Jest vs. Playwright)

• Jest + RTL ([ComponentName].test.tsx):
  • Schnelle Feedback-Schleife in jsdom.
  • Prop-Permutationen, bedingte UI-Elemente und leere/null-Zustände.
  • Benutzerinteraktionen über @testing-library/user-event (niemals fireEvent).
  • Next.js-Routing-Mocks (useRouter, usePathname, useSearchParams aus next/navigation).
  • next-intl Wörterbuch-Interpolation und Pluralisierungsprüfungen innerhalb von NextIntlClientProvider.
  • Zugängliche Rollenabfragen (screen.getByRole) und automatisierte A11y-Checks (jest-axe).
• Playwright ([ComponentName].spec.ts oder seitenbezogene Specs):
  • Echte Browserausführung (Chromium/WebKit/Firefox).
  • Instant Shell Assertions (@next/playwright): Verwende den instant(page, ...)-Helper, um zu bestätigen, dass statische Shells und vorabgerufene App Shells sofort rendern, bevor dynamisches Server-Streaming aufgelöst wird.
  • Null-Hydrierungskonflikte: Höre auf Browser-Konsole-Ereignisse (page.on('console')), um React SSR-Hydrierungswarnungen zu erkennen und Tests fehlschlagen zu lassen.
  • Visuelle & BiDi-Regression: Verwende expect(page).toHaveScreenshot() über Themes (helle vs. dunkle OKLCH-Variablen) und Textrichtungen (dir="ltr" vs. dir="rtl").
  • Netzwerkresilienz: Verwende page.route(), um langsame Netzwerkantworten zu testen (überprüft, ob Suspense-Skelette geometrisch übereinstimmen, um CLS zu verhindern) und 500-Fehlergrenzen.
• Detaillierte Teststandards: Konsultiere references/testing-architecture-guide.md.

---

Phase 0: Implementierungsplan & Genehmigungs-Gate

[!IMPORTANT] Vor der Ausführung planen: Generiere und präsentiere immer ein implementation_plan.md-Artefakt, das alle geplanten Dateierstellungen, -änderungen, TypeScript-Verträge, Übersetzungswörterbuch-Ergänzungen und TDD-Testfälle dokumentiert, bevor Schreiboperationen ausgeführt, Wörterbücher geändert oder Komponenten im Repository erstellt werden. Warte auf die Bestätigung/Genehmigung des Benutzers, bevor du mit der Ausführung fortfährst.

Der Implementierungsplan muss Folgendes abdecken:

1. Zielarchitektur & -pfad: Vollständiges Zielverzeichnis (<new_component_dir>/<page_or_global>/<ComponentName>/) und Klassifizierung (RSC vs. Client Leaf-Komponente).
2. Konsultierte Next.js Lokale Docs: Bestimmte Doc-Pfade geprüft unter node_modules/next/dist/docs/ (z.B. 04-api-reference/04-components/image.md, 03-directives/use-cache.md, 04-api-reference/02-functions/use-router.md).
3. TypeScript-Verträge: Prop-Interfaces und Typen mit strengen englischen TSDoc-Anmerkungen.
4. Wörterbuchstrategie: Explizite Übersetzungs-Namespaces und Schlüssel, die zu messages/[locale].json für alle supported_languages in docs/project.json hinzugefügt werden sollen (null hartcodierte Strings oder In-File-Mock-Wörterbücher).
5. Theme-Tokens & Styling: Identifizierte semantische OKLCH-CSS-Variablen und logische Layout-Klassen.
6. Test- & Diagnosestrategie:
   • Jest Unit-Tests ([ComponentName].test.tsx): Mock-Konfigurationen (next/navigation), Prop-Variationen, Callback-Assertions, NextIntlClientProvider-Integration und A11y-Rollenabfragen.
   • Playwright Integrationsszenarien ([ComponentName].spec.ts): Visuelle Snapshot-Ziele (helle/dunkle Theme-Tokens, LTR vs. RTL logische Layouts), Netzwerkdrosselung/Skelett-Geometrie-Prüfungen und Hydrierungs-Verifikations-Listener.
   • Next DevTools Diagnose: Runtime-Fehler- und Kompilierungsprüfungen über next-devtools.
7. Verifikations-Gate: Exakte Verifikationsbefehle zum Ausführen (verify-dev.ps1, gezielte Unit-Tests und Playwright E2E-Specs).

---

Workflow-Schritte

• Schritt 0: Implementierungsplan-Generierung & Genehmigungs-Gate

  • node_modules/next/dist/docs über codebase-memory MCP (search_code, search_graph) nach Next.js-APIs, Direktiven, Hooks oder Komponenten durchsuchen, die von der geplanten Komponente verwendet werden, um einen aktuellen Kontext sicherzustellen.
  • Komponentenanforderungen synthetisieren, docs/project.json scannen und implementation_plan.md generieren, das konsultierte Docs und Verträge dokumentiert.
  • request_feedback = true und user_facing = true auf dem Artefakt setzen.
  • Auf Überprüfung und explizite Genehmigung durch den Benutzer warten, bevor Code geschrieben wird.

• Schritt 1: Dev-Server-Verifikation & Next DevTools-Verbindung

  • next-devtools MCP über nextjs_index abfragen, um laufende Next.js Dev-Server-Instanzen zu erkennen.
  • Wenn Dev-Server läuft: In den aktiven Port und die Server-Instanz einklinken; ohne Neustart weiterentwickeln.
  • Wenn Dev-Server NICHT läuft: Den Dev-Server im Hintergrund starten (pnpm dev, IsDaemon: true) und die Erkennung mit nextjs_index verifizieren.

• Schritt 2: Wörterbuchbefüllung & TypeScript-Vertragsdefinition

  • docs/project.json lesen, um dictionaries_dir (messages ist Standard) und supported_languages zu ermitteln.
  • Den Übersetzungs-Namespace und die Schlüssel der Komponente definieren.
  • Alle Wörterbuchdateien befüllen (messages/en.json, messages/fa.json, usw.) mit authentischen Übersetzungen für jede unterstützte Sprache, bevor JSX geschrieben wird.
  • Prop-Interfaces mit strengen englischen TSDoc-Anmerkungen definieren (@param, @defaultValue, @returns).
  • Wenn es mehr als eine unterstützte Sprache gibt, muss die Komponente zuerst die Übersetzung abrufen und bei Fehlschlag Fallbacks verwenden.

• Schritt 3: TDD-Baseline Unit-Tests ([ComponentName].test.tsx via Jest + RTL)

  • [ComponentName].test.tsx VOR der Implementierung der Komponente schreiben.
  • next/navigation-Hooks mocken (useRouter, usePathname, useSearchParams).
  • Gerenderte Komponenten in NextIntlClientProvider einwickeln, der die Wörterbuch-messages und die aktive locale bereitstellt.
  • Richtungsattribute (dir="rtl" vs. dir="ltr"), Standard-Props, interaktive Callbacks (@testing-library/user-event), Suspense-Skelett-Fallbacks und semantische ARIA-Rollen testen.

• **Schritt 4

…

[für die Übersetzung gekürzt]