BIGboss248/nextjs-wordpress

Next.js WooCommerce Integration (nextjs-woocommerce)

Betriebshandbuch und Checkliste für die Architektur, Abfrage und Integration von Next.js App Router Anwendungen mit einem headless WooCommerce-Backend über WPGraphQL, WooGraphQL und JWT-Authentifizierung.

---

Voraussetzungen und Dokumentationsreferenzen

• Next.js 14+ Projekt initialisiert mit App Router und TypeScript.
• Aktives WooCommerce-Backend mit WPGraphQL, WooGraphQL und wp-graphql-jwt-authentication.
• Für vollständige API-Schemas und Next.js-Code-Muster siehe nextjs-woocommerce-reference.md.
• Für die Implementierung eines wiederverwendbaren Datenabruf-Clients siehe woocommerce-fetcher.ts.

---

Schritt-für-Schritt-Implementierungscheckliste

flowchart TD
    S1["1. Umgebungs- & Client-Setup"] --> S2["2. Öffentlicher Produktkatalog (ISR/SSG)"]
    S2 --> S3["3. Benutzerauthentifizierung (JWT + Cookies)"]
    S3 --> S4["4. Geschütztes Profil & Bestellhistorie"]
    S4 --> S5["5. Warenkorbsitzung & nativer Checkout-Bridge"]

Phase 1: Umgebungs- und Client-Konfiguration

• Umgebungsvariablen konfigurieren:
  • Füge NEXT_PUBLIC_WORDPRESS_API_URL=https://your-store.com/graphql zu .env.example und .env.development hinzu.
  • Füge NEXT_PUBLIC_WORDPRESS_URL=https://your-store.com für Checkout-Weiterleitungen hinzu.
• Universellen Fetcher einrichten:
  • Implementiere woocommerce-fetcher.ts mit Unterstützung für ISR-Caching und Authentifizierungs-Header.

Phase 2: Öffentlicher Produktkatalog und Taxonomien

• Kategorienavigation: Abfrage von productCategories mit hideEmpty: true für Kopfzeilen und Kategorienmenüs.
• Produktübersichtsarchiv: Abfrage von products mittels Union-Fragmenten (... on SimpleProduct, ... on VariableProduct). Konfiguriere next: { revalidate: 300, tags: ['products'] }.
• Produktdetailseite: Vorab-Rendering dynamischer Routen (app/products/[slug]/page.tsx) mit generateStaticParams(), das alle Produkt-Slugs abfragt.

Phase 3: JWT-Authentifizierungspipeline

• Login-Mutation: Implementiere eine Server-Aktion, die login(input: { username, password }) ausführt.
• Cookie-Speicherung: Speichere den zurückgegebenen authToken in einem sicheren HttpOnly-Cookie (auth_token).
• Sitzungsbindung: Falls der Kunde sessionToken zurückgibt, speichere dies im wc_session-Cookie.
• Logout: Lösche Authentifizierungs-Cookies beim Benutzer-Logout.

Phase 4: Geschützte Benutzerdaten und Bestellungen

• Kundenprofil: Abfrage von viewer { id name email } mit Authorization: Bearer <authToken>.
• Bestellhistorie: Abfrage von customer { orders { nodes { id orderNumber total status } } } mit cache: 'no-store'.

Phase 5: Warenkorbverwaltung und Checkout-Strategie

• Warenkorbzustand: Erfasse und persistiere den woocommerce-session-Header, der bei addToCart-Mutationen zurückgegeben wird.
• Nativer Checkout-Bridge:
  • Leite Benutzer zu https://your-store.com/checkout weiter, um native WooCommerce-Zahlungsgateways (ZarinPal, Mellat, Stripe), regionale Logistik und Compliance-Siegel ohne benutzerdefinierte Gateway-Neufassungen zu nutzen.

---

Grenzfälle und bekannte Fallstricke

1. Statische vs. dynamische Deoptimierung: Das Lesen von Cookies im Root-Layout oder auf Produktseiten versetzt Next.js in den vollständigen SSR-dynamischen Modus. Lies Authentifizierungs-Cookies nur innerhalb von Server-Aktionen, Routen-Handlern oder isolierten Account-Dashboard-Unterbäumen (app/account/...).
2. Polymorphe Fragmente: Direkte Abfragen wie products { nodes { price } } schlagen bei der Validierung in WooGraphQL fehl. Umschließe Preis- und Variationsfelder immer mit ... on SimpleProduct und ... on VariableProduct.
3. Sitzungsverlust: Wenn Artikel zum Warenkorb hinzugefügt werden, erzeugt das erneute Senden des woocommerce-session-Headers bei jeder Mutation einen neuen leeren Warenkorb, sofern dies nicht korrekt erfolgt.
4. CORS am GraphQL-Endpunkt: Stelle sicher, dass WordPress die Header Access-Control-Allow-Origin und Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session für deine Next.js-Domain sendet.

---

Überprüfung und Pre-Flight-Tests

• pnpm build wird erfolgreich mit statischer Generierung der Produktseiten ausgeführt.
• Teste, ob das Login-Formular ein auth_token ausgibt und zum Dashboard weiterleitet.
• Die Account-Seite rendert Kundendetails und die Bestellliste mit gültigem Token.
• Der "In den Warenkorb"-Button aktualisiert die Artikelanzahl im Warenkorb bei mehreren Client-Anfragen.