Headless Starter Kit — Vollständiger Leitfaden

Dieser Leitfaden behandelt die vollständige Installation, Konfiguration und Nutzung von Headless Starter Kit — dem WordPress-Plugin, das Ihren WooCommerce-Shop in einen Headless-Commerce verwandelt, begleitet von einem schlüsselfertigen Next.js-15-Starter.

Überblick

Headless Starter Kit besteht aus zwei Lieferungen in einem Kauf:

1. Das WordPress-Plugin (ZIP hochgeladen unter /wp-admin/plugins.php), das im Backend Folgendes bereitstellt: JWT-Authentifizierung, Warenkorb-API, Checkout-Brücke, öffentlicher Config-Endpunkt, ISR-Webhooks und striktes CORS.
2. Der Next.js-15-Starter (ZIP herunterladbar aus dem WordPress-Admin, sobald das Plugin aktiviert und konfiguriert ist), der ein vollständiges Next.js-Projekt mit Seiten für Startseite, Liste, ISR-Produktdetailseite, Warenkorb, Checkout, Login, Registrierung und Kundenkonto enthält — Umgebungsvariablen bereits mit Ihren URLs und Secrets vorausgefüllt.

Die Architektur ist bewusst einfach: Ihr WooCommerce bleibt die Quelle der Wahrheit (Produkte, Bestellungen, Lagerbestand, Zahlungen), und Next.js konsumiert die REST-API über sichere Proxy-Routen. Keine Datenbank-Duplizierung, keine Replikation zu verwalten.

Voraussetzungen

WordPress-Seite

• WordPress 6.4 oder höher
• WooCommerce 8.0 oder höher (getestet bis 9.5)
• PHP 8.1 oder höher
• Permalinks auf Beitragsname eingestellt (nicht auf Einfach)
• HTTPS aktiv (unerlässlich für httpOnly-Cookies und Authentifizierung in Produktion)
• Ein WooCommerce-REST-Schlüsselpaar mit Lese-/Schreibrechten (generiert unter WooCommerce → Einstellungen → Erweitert → REST-API)

Next.js-Frontend-Seite

• Node.js 20 oder höher (empfohlen: Versionen mit nvm verwalten)
• Node-kompatibles Hosting: Vercel, Hetzner VPS, Netlify, Railway oder jeder Server, der Node 20+ ausführen kann

Installation des WordPress-Plugins

1. Gehen Sie im WordPress-Back-Office zu Plugins → Neues Plugin hinzufügen → Plugin hochladen.
2. Wählen Sie die Datei dfheadlessstarterkit.zip aus, klicken Sie dann auf Jetzt installieren.
3. Klicken Sie auf Plugin aktivieren.
4. Ein neues Menü Headless Kit erscheint in der linken Seitenleiste mit drei Tabs: Einstellungen, Diagnose, Starter herunterladen.

Bei der Aktivierung erzeugt das Plugin automatisch einen zufälligen JWT-Secret und ein Revalidierungs-Token. Sie können sie jederzeit über die Einstellungen neu generieren.

Konfiguration

Öffnen Sie Headless Kit → Einstellungen. Jeder Abschnitt ist unabhängig und kann angepasst werden, ohne etwas neu zu starten.

Frontend-URL

Geben Sie die vollständige öffentliche URL Ihrer Next.js-App ohne abschließenden Schrägstrich ein. Beispiel:

https://shop.beispiel.de

Diese URL dient drei Zwecken: dem Aufbau der ISR-Webhooks, dem Befüllen der Variable NEXT_PUBLIC_SITE_URL im gelieferten Starter und der Validierung des standardmäßigen CORS-Ursprungs.

JWT-Secret und Revalidierungs-Token

Zwei Secrets werden verwendet:

• JWT-Secret — signiert Access- und Refresh-Tokens. Mindestens 32 Zeichen. Niemals teilen.
• Revalidierungs-Token — im Header Authorization: Bearer … der ISR-Webhooks gesendet. Muss identisch mit der Variable REVALIDATE_TOKEN auf der Next.js-Seite sein.

Ein Neu generieren-Button neben jedem Feld erzeugt einen kryptografisch starken Zufalls-Secret über crypto.getRandomValues.

Warenkorb-Modus: JWT oder Server?

Die Wahl erfolgt über einen Radio-Button in den Einstellungen.

JWT-Modus (Standard, empfohlen)

Der gesamte Warenkorb wird in ein signiertes HS256-Token serialisiert und über den Header X-DFHSK-Cart zurückgegeben. Auf der WordPress-Seite werden keine Daten gespeichert. Ideal für:

• Deployments auf Vercel Edge, Cloudflare oder Multi-Instance-Setups
• Shops mit viel Traffic, bei denen es sich lohnt, die Datenbank bei jedem Aufruf zu umgehen
• Setups, in denen WordPress rein als API dient und keine Sessions braucht

Server-Modus (WC_Session)

Der Warenkorb lebt in der nativen WC_Session-Tabelle von WooCommerce. Zu bevorzugen, wenn:

• Sie WooCommerce-Erweiterungen verwenden, die in den Warenkorb eingreifen (WooCommerce Subscriptions, Dynamic Pricing, YITH-Plugins usw.)
• Sie die native Session-Logik von WooCommerce beibehalten möchten (native Abandoned-Cart-Erinnerungen, serverseitiges Cross-Selling usw.)

CORS-Ursprünge

Eine strikte Allow-List von Ursprüngen, die die API aufrufen dürfen. Ein Ursprung pro Zeile, volles https://…-Format. Subdomain-Wildcards werden unterstützt:

https://shop.beispiel.de
https://preview.beispiel.de
https://*.previews.beispiel.de
http://localhost:3000

ISR-Ereignisse

Fünf Kontrollkästchen legen fest, welche WordPress-Ereignisse einen ISR-Webhook zu Next.js auslösen:

• Produkte — save_post_product, woocommerce_update_product
• Kategorien — Erstellung, Aktualisierung, Löschung von Begriffen der Taxonomie product_cat
• Bestellungen — Statusänderungen (nützlich zum Aktualisieren der Kontoseite)
• Seiten — save_post_page
• Gutscheine — Erstellung und Aktualisierung von Rabattcodes

Ein Zu revalidierende Pfade-Textbereich erlaubt Ihnen, präzise festzulegen, welche Next.js-Pfade für jedes Ereignis revalidiert werden (standardmäßig leitet das Plugin die betroffenen Pfade intelligent ab).

Diagnose

Headless Kit → Diagnose. Elf automatische Prüfungen werden bei jeder Anzeige der Seite ausgeführt:

1. WooCommerce aktiv — die Klasse WooCommerce ist verfügbar
2. Saubere Permalinks — die Struktur ist nicht Einfach
3. REST-API erreichbar — /wp-json/ antwortet mit 200
4. HTTPS aktiv — is_ssl() gibt true zurück
5. WPGraphQL erkannt — nur zur Information, nicht blockierend
6. JWT-Secret definiert — mindestens 32 Zeichen
7. Frontend-URL konfiguriert — nicht leer und gültiges URL-Format
8. CORS-Ursprünge gesetzt — mindestens ein Ursprung
9. Revalidierungs-Token definiert — mindestens 24 Zeichen
10. WooCommerce-REST-Schlüssel — das Plugin erkennt ein aktives consumer_key/consumer_secret-Paar
11. Warenkorb-Modus lesbar — der gewählte Speicher funktioniert

Jede Prüfung zeigt grün (OK), orange (Warnung, nicht blockierend) oder rot (blockierend) an. Beheben Sie alles Rote, bevor Sie in Produktion gehen.

Herunterladen und Starten des Next.js-Starters

Sobald die Einstellungen ausgefüllt und die Diagnose grün sind, öffnen Sie Headless Kit → Starter herunterladen. Klicken Sie auf den großen Button Next.js-Starter herunterladen.

Das gelieferte ZIP ist ein vollständiges Next.js-15-Projekt, das on-the-fly mit Ihren bereits injizierten URLs und Secrets generiert wird. Platzhalter, die bei der Generierung ersetzt werden:

• {{SITE_URL}} → URL Ihres WordPress
• {{FRONTEND_URL}} → konfigurierte Frontend-URL
• {{REVALIDATE_TOKEN}} → Ihr Revalidierungs-Token
• {{CURRENCY}} → WooCommerce-Währung
• {{SITE_NAME}} → Site-Titel
• {{LOCALE}} → WordPress-Locale (de, en, fr, etc.)

Die Datei .envtmpl wird bei der Generierung in .env.example umbenannt.

Manuell auszufüllende Umgebungsvariablen

Einige Werte können nicht automatisch abgerufen werden — Sie müssen sie in der .env-Datei (erstellt aus .env.example) hinzufügen:

WOO_REST_CONSUMER_KEY=ck_xxxxxxxxxxxxxx
WOO_REST_CONSUMER_SECRET=cs_xxxxxxxxxxxxxx
SESSION_PASSWORD=Ihr-Passwort-mindestens-32-Zeichen

Erzeugen Sie ein starkes SESSION_PASSWORD:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Lokale Entwicklung

npm install
cp .env.example .env
# Bearbeiten Sie .env mit Ihren fehlenden Secrets
npm run dev

Das Frontend wird unter http://localhost:3000 ausgeliefert. Fügen Sie diese URL während der Entwicklung zu den CORS-Ursprüngen auf der WordPress-Seite hinzu.

Deployment auf Vercel

npx vercel link
npx vercel env pull .env.production
npx vercel deploy --prod

Konfigurieren Sie danach alle Umgebungsvariablen im Vercel-Dashboard (Project → Settings → Environment Variables). Die gelieferte vercel.json-Datei fixiert die Region auf cdg1 (Paris) und deaktiviert den Cache auf den Routen /api/*.

Deployment auf Hetzner (oder jedem Ubuntu/Debian VPS)

# Auf dem Server, als root oder mit sudo
git clone ihr-repo.git storefront && cd storefront
cp .env.example .env
nano .env                       # Alle Variablen ausfüllen
bash deploy/hetzner.sh

Das Skript installiert Docker bei Bedarf, baut das Image, startet den Container und stellt den Dienst auf 127.0.0.1:3000 bereit. Fügen Sie Caddy oder nginx als Reverse-Proxy für TLS hinzu. Minimales Caddyfile-Beispiel:

shop.beispiel.de {
  encode zstd gzip
  reverse_proxy 127.0.0.1:3000
}

Bereitgestellte REST-Endpunkte

Alle Plugin-Endpunkte liegen unter dem Namespace dfhsk/v1. Vollständige URL: https://beispiel.de/wp-json/dfhsk/v1/…

Authentifizierung

• POST /auth/login — Body: { username, password } → gibt { token, refresh_token, user } zurück
• POST /auth/refresh — Body: { refresh_token } → gibt ein neues token zurück
• GET /auth/me — Header: Authorization: Bearer … → gibt den aktuellen Nutzer zurück
• POST /auth/register — Body: { email, password, first_name, last_name }
• POST /auth/logout — invalidiert den Refresh-Token

Warenkorb

Jeder Aufruf übermittelt das Warenkorb-Token über den Header X-DFHSK-Cart. Der Server gibt bei jeder Antwort ein neues Token im selben Header zurück.

• GET /cart — vollständiger Snapshot (Artikel, Summen, Steuern, Versand)
• POST /cart/add — Body: { product_id, quantity, variation? }
• POST /cart/update — Body: { key, quantity }
• POST /cart/remove — Body: { key }
• POST /cart/coupon — Body: { code }
• DELETE /cart/coupon/{code}
• POST /cart/shipping — Body: { country, postcode } → gibt anwendbare Tarife zurück
• POST /cart/clear

Checkout

• POST /checkout/create-order — Body: { payment_method, billing, shipping? } → gibt { order_id, order_key, redirect } zurück. Das redirect ist die URL zum Zahlungs-Gateway (Stripe, PayPal usw.).
• GET /checkout/order/{id} — Header Authorization: Bearer … erforderlich

Öffentliche Konfiguration

• GET /config — ohne Authentifizierung zugänglich. Gibt { currency, base_country, countries, payment_methods, tax_settings } zurück. Der Next.js-Starter verwendet diesen Endpunkt, um die Checkout-Formulare zu hydratisieren.

ISR-Webhooks (Next.js-Seite)

Das Plugin sendet POST-Anfragen an {FRONTEND_URL}/api/revalidate mit dem Header Authorization: Bearer {REVALIDATE_TOKEN}. Der Body ist JSON:

{
  "paths": ["/products/leinenjacke", "/products"],
  "tags": ["product:leinenjacke"],
  "reason": "wc_update_product"
}

Die im Starter gelieferte Route /api/revalidate validiert das Token und ruft dann für jeden Eintrag revalidatePath und revalidateTag auf.

Starter anpassen

Der gelieferte Code steht unter GPL v2 — Sie können ihn ohne Einschränkung modifizieren, erweitern und weitergeben. Übliche Einstiegspunkte:

• Farbpalette: tailwind.config.ts, brand-Palette (standardmäßig Orange)
• Shop-Komponenten: src/components/shop/ (Header, Footer, ProductCard, CartProvider)
• Öffentliche Seiten: src/app/(shop)/
• Kundenkonto-Seiten: src/app/(auth)/
• Preis- und Datumsformatierung: src/lib/format.ts
• TypeScript-Typen: src/types/woo.ts
• API-Aufruf-Helfer: src/lib/woo-rest.ts (Funktionen wooRest und dfhskFetch)

Problembehebung

CORS-Fehler in der Browser-Konsole

Der Frontend-Ursprung steht nicht in der Allow-List. Fügen Sie ihn unter Einstellungen → CORS-Ursprünge hinzu, einen pro Zeile, ohne abschließenden Schrägstrich.

ISR-Webhooks antworten 401

Das REVALIDATE_TOKEN auf der Next.js-Seite stimmt nicht mit dem in WordPress konfigurierten Token überein. Kopieren Sie den exakten Wert aus den WP-Einstellungen in die Next.js-.env-Datei und deployen Sie erneut.

Login gibt 403 trotz korrekter Zugangsdaten zurück

Prüfen Sie, dass das Benutzerkonto ein Passwort hat (nicht nur Social-Login), dass HTTPS in Produktion aktiv ist und dass der JWT-Secret mindestens 32 Zeichen lang ist. Prüfen Sie den Diagnose-Tab.

Der Warenkorb leert sich zwischen zwei Seiten

Prüfen Sie im JWT-Modus, ob der Starter das Token korrekt in localStorage liest und schreibt (Schlüssel dfhsk_cart_token). Öffnen Sie den Browser-Inspector → Tab Application → Local Storage.

Eine in WooCommerce erstellte Bestellung erscheint nicht in Next.js

Prüfen Sie, ob das Ereignis Bestellungen in den ISR-Ereignissen aktiviert ist und ob der Webhook fehlerfrei durchgeht (aktivieren Sie WP_DEBUG_LOG).

Weiterführendes

Der Starter ist ein Ausgangspunkt, kein fertiges Produkt. Je nach Projekt ziehen Sie in Betracht, Folgendes hinzuzufügen:

• Eine Instant-Suchmaschine (Algolia, Meilisearch, Typesense), die von denselben ISR-Webhooks gefüttert wird
• Ein CMS für redaktionellen Inhalt auf WordPress-Seite mit dem ACF-Plugin oder ähnlichem und eine dedizierte Next.js-Seite
• Eine PWA mit Service Worker für den Offline-Modus (siehe auch unser Modul dfpwa)
• Echtzeit-KI-Personalisierung (siehe dfsmartcontent)

Bei technischen Fragen kontaktieren Sie den DataFirefly-Support mit Ihren Logs und den Ergebnissen des Diagnose-Tabs.