# Headless Starter Kit — Vollständiger Leitfaden

> Vollständiger Installations-, Konfigurations- und Deployment-Leitfaden für Headless Starter Kit: das WordPress-Plugin, das Ihren WooCommerce-Shop in einen Headless-Commerce verwandelt, mit vorkonfiguriertem, schlüsselfertigem Next.js-15-Starter.

- Seite: <https://www.datafirefly.com/de/documentation/headless-starter-kit/>
- Sprache: de
- Aktualisiert am: 2026-07-01
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/headless-starter-kit/index.md), [en](https://www.datafirefly.com/en/documentation/headless-starter-kit/index.md), [es](https://www.datafirefly.com/es/documentation/headless-starter-kit/index.md), [it](https://www.datafirefly.com/it/documentation/headless-starter-kit/index.md), [pl](https://www.datafirefly.com/pl/documentation/headless-starter-kit/index.md), [nl](https://www.datafirefly.com/nl/documentation/headless-starter-kit/index.md), [pt](https://www.datafirefly.com/pt/documentation/headless-starter-kit/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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.

**Für wen dieser Leitfaden gedacht ist.** Entwickler, Agenturen oder technisch versierte Händler, die einen bestehenden WooCommerce-Shop auf headless umstellen wollen, ohne Authentifizierung, Warenkorb und Checkout neu zu erfinden. Sie sollten mit der Kommandozeile und Node.js vertraut sein und etwas Serverkonfiguration nicht scheuen, wenn Sie sich für Hetzner entscheiden.

## Ü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

**Klassisches Shared Hosting (o2switch, geteiltes OVH, etc.) ist nicht geeignet**, um das Next.js-Frontend zu hosten, das eine persistente Node-Laufzeit benötigt. Das WordPress-Plugin läuft dagegen auf jedem WP-kompatiblen Hosting.

## 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`.

**Nach der Neugenerierung des JWT-Secrets werden alle bestehenden Access- und Refresh-Tokens ungültig.** Nutzer müssen sich erneut anmelden. Warnen Sie sie oder tun Sie es außerhalb der Stoßzeiten.

### 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
```

Fügen Sie während der Entwicklung `http://localhost:3000` hinzu und entfernen Sie es dann in Produktion.

### 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`)

Um eine neue Seite hinzuzufügen, die zum Beispiel Produkte einer Marke listet, duplizieren Sie `src/app/(shop)/products/page.tsx` und passen Sie die WooCommerce-REST-Abfrage an. Die Funktion `wooRest()` kümmert sich automatisch um die Basic-Authentifizierung.

## 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.