WordPress Headless umbauen: 6 Herausforderungen und ihre Lösungen

Ein Headless-WordPress-Projekt ist kein einfacher Spaziergang. Unser Team hat GlobeVM, einen Cloud-, IT- und Cybersecurity-Anbieter, von einem monolithischen WordPress-System in eine Headless-Architektur überführt. Dabei stießen wir auf sechs zentrale Herausforderungen, die wir mit maßgeschneiderten Lösungen gemeistert haben. Wer vor einem ähnlichen Projekt steht, sollte diese Erkenntnisse kennen – sie können Wochen an Debugging-Arbeit ersparen.

Warum Headless WordPress? Effizienz und Flexibilität im Fokus

Der Hauptgrund für den Umstieg lag in der Performance und der modernen Frontend-Entwicklung. Mit Next.js auf Vercel und WordPress als Headless-CMS konnten wir dynamische Inhalte mit statischer Seitenauslieferung kombinieren. Das Ergebnis: schnellere Ladezeiten, eine bessere Benutzererfahrung und eine zukunftssichere Architektur. Doch der Weg dorthin war steinig – und voller unerwarteter Hürden.

Herausforderung 1: Die WordPress-REST-API – Vom Chaos zur Effizienz

Unser ursprünglicher Ansatz bestand darin, die Standard-WordPress-REST-API direkt aus Next.js anzusprechen. Das führte zu einem wahren Flickenteppich an API-Aufrufen: Für die Blog-Startseite mussten wir acht separate fetch-Anfragen stellen – für Beiträge, Autoren, Kategorien, Tags und benutzerdefinierte Felder. Zudem behinderten unübersichtliche Parameter wie ?_fields=id,title,acf&_embed die Wartung.

Die Lösung: ein Backend-For-Frontend (BFF). Statt Next.js mit der Logik zu belasten, entwickelten wir ein maßgeschneidertes PHP-Plugin für WordPress. Dieses Plugin aggregierte alle benötigten Daten in einem einzigen Endpunkt (/wp-json/gvm/v1/blog-home). WordPress führte die komplexen Datenbankabfragen aus, kombinierte die Ergebnisse in einem strukturierten JSON-Array und speicherte diese zwischengespeichert in RAM – dank Transients und Redis. Das Ergebnis? Next.js musste nur noch eine einzige API-Anfrage stellen. Die Seite lädt nun in Millisekunden.

Herausforderung 2: SVG-Icons und ACF-Felder – Wenn WordPress Grenzen setzt

Unser Design setzte auf benutzerdefinierte SVG-Icons, doch WordPress blockiert standardmäßig den Upload von SVG-Dateien aus Sicherheitsgründen. Zudem gestaltete sich die Integration von ACF-Bildfeldern mit Next.js als knifflig.

Die Lösung boten zwei Ansätze:

• Plugin-basiert: Der Einsatz des Plugins Safe SVG ermöglichte den sicheren Upload von SVG-Dateien im WordPress-Backend.
• Code-basiert: Wer auf Plugins verzichten wollte, konnte WordPress mit PHP-Code anpassen. Eine KI-Unterstützung half dabei, die notwendigen Anpassungen schnell umzusetzen.

Herausforderung 3: Ein Headless-Kommentarsystem mit strengen Regeln

Unsere Anforderungen waren klar: Kommentare mussten zunächst von einem Administrator freigeschaltet werden, und die Diskussionsebenen durften maximal eine Ebene tief sein – also keine Antworten auf Antworten.

Die Lösung bestand aus drei Komponenten:

• GET-API: Ein benutzerdefinierter Endpunkt holte alle freigeschalteten Kommentare ab und strukturierte sie als Parent-Child-Baum in JSON.
• POST-API: Ein weiterer Endpunkt nahm neue Kommentare entgegen.
• Sicherheit: Um zu verhindern, dass Nutzer die Regeln übergingen (z. B. per Postman), entwickelte unser Team eine PHP-Funktion namens Absolute Root Finder. Diese Funktion zwang Kommentare, die an eine Antwort gerichtet waren, zurück zur obersten Ebene. Zudem entfernten wir den „Antworten“-Button im WordPress-Dashboard für bereits beantwortete Kommentare – per Filter (comment_row_actions).

Herausforderung 4: View-Counter in einer statischen Welt – Wie misst man Leserzahlen?

Ein „Beliebte Artikel“-Abschnitt sollte auf Basis von Seitenaufrufen sortiert werden. Doch hier lag das Problem: Next.js nutzt ISR (Incremental Static Regeneration), um statische HTML-Seiten auszuliefern. WordPress erhält daher keine Rückmeldung, wenn ein Nutzer einen Artikel liest.

Die Lösung war ein unsichtbarer Tracker: Bei jedem Seitenaufruf eines Blogartikels in Next.js startete eine clientseitige useEffect-Funktion, die eine POST-Anfrage an einen benutzerdefinierten WordPress-Endpunkt (/wp-json/abc/v1/track-view/15) sandte. WordPress erhöhte daraufhin einen benutzerdefinierten Meta-Wert um eins. Der Endpunkt /popular-posts konnte nun die Artikel nach diesem Meta-Wert sortieren – eine einfache, aber hochwirksame Lösung.

Herausforderung 5: WordPress-Vorschau in einer Next.js-Umgebung – Wie funktioniert das?

Das größte Rätsel: Wie lässt sich die WordPress-Vorschaufunktion nutzen, wenn das Frontend auf Vercel läuft?

Die Lösung basierte auf einem Trick mit dem preview_post_link-Filter. Wenn ein Administrator im WordPress-Backend auf „Vorschau“ klickte, leitete WordPress den Nutzer zu einer speziellen Vercel-URL weiter: vercel.app/api/preview?secret=SUPER_SECRET_TOKEN&preview_id=42&route=blog. Next.js überprüfte das geheime Token, aktivierte den Draft Mode und lud den Entwurf basierend auf der route-Parameter direkt aus WordPress. Zudem nutzten wir Application Passwords (HTTP Basic Auth), um den Zugriff auf unveröffentlichte Entwürfe zu sichern. Ein PHP-basiertes Autosave-System (wp_get_post_autosave) sorgte dafür, dass Administratoren ihre Änderungen in Echtzeit sehen konnten – ohne den Entwurf vorher speichern zu müssen.

Herausforderung 6: Das Double-Cache-Problem – Wenn zwei Caches sich in die Quere kommen

In der Produktion stießen wir auf ein klassisches Problem: Next.js cached das Frontend, WordPress das Backend. Wurde ein Artikel aktualisiert, blieb die Website unverändert, da Vercel weiterhin die veraltete JSON-Antwort von WordPress erhielt.

Die Lösung bestand darin, alle traditionellen WordPress-Caching-Plugins (wie WP Rocket oder Breeze) zu deaktivieren – sie sind für Headless-APIs ungeeignet. Stattdessen setzten wir auf:

• Redis Object Cache: Zur Beschleunigung der Datenbankabfragen.
• On-Demand Revalidation: Mit dem Plugin WP Webhooks lösten wir das Problem. Jedes Mal, wenn ein Administrator einen Artikel aktualisierte, sandte WordPress einen Webhook an Vercel. Dieser löschte sofort den Cache für die betroffene URL.

Ein Hinweis zur ISR-Technologie:

Next.js bietet zwei Ansätze zur Cache-Verwaltung: On-Demand Revalidation und Time-Based Revalidation. Bei der On-Demand-Variante wird der Cache erst nach einer Anfrage aktualisiert – der erste Besucher sieht also die veraltete Version, während der zweite die aktualisierte Version erhält. Time-Based Revalidation hingegen setzt ein festes Zeitintervall, nach dem der Cache automatisch erneuert wird. Beide Methoden kombinieren die Vorteile von SSG (Static Site Generation) mit der Dynamik eines SSR (Server-Side Rendering)-Caches.

Fazit: Headless WordPress lohnt sich – mit der richtigen Vorbereitung

Der Umstieg auf eine Headless-Architektur ist kein Projekt für schwache Nerven. Doch die Mühe lohnt sich: schnellere Ladezeiten, eine moderne Frontend-Entwicklung und eine skalierbare Infrastruktur sind nur einige der Vorteile. Die größten Herausforderungen lagen nicht in der Technologie selbst, sondern in der Integration von WordPress mit modernen Frontend-Frameworks. Mit den hier vorgestellten Lösungen lassen sich typische Fallstricke vermeiden. Wer diese Schritte beherzigt, spart Zeit, vermeidet Frustration und kann sich auf das Wesentliche konzentrieren: ein performantes, zukunftssicheres Webprojekt.