Headless WordPress mit Next.js

Headless bedeutet: WordPress behält das Backend, gibt aber die Darstellung ab. Die Inhalte werden über die REST API abgerufen und von einem eigenen Frontend gerendert – häufig mit Next.js. Der Ansatz ist mächtig und wird oft überschätzt: Für viele Websites ist er teurer und umständlicher als ein gutes Block-Theme. Diese Lektion zeigt, wann er sich lohnt, wie der Aufbau technisch aussieht und welche Funktionen dabei verloren gehen – damit Sie die Entscheidung begründet treffen können.

1. Der Aufbau

Abb. 4.1Klassisch und headless im Vergleich

2. Inhalte abrufen

Im Frontend wird der Inhalt zur Bauzeit oder beim Aufruf geholt. Moderne Frameworks speichern die Antwort zwischen und erneuern sie nach einer festgelegten Zeit; so bleiben Seiten schnell, ohne dass bei jedem Besuch WordPress angefragt wird. Wichtig ist, nur die benötigten Felder zu holen und Fehler abzufangen – ist WordPress kurz nicht erreichbar, soll die Website nicht ausfallen.

1const WP = 'https://cms.beispiel.de/wp-json/wp/v2';
2
3async function beitrag( slug: string ) {
4  const antwort = await fetch(
5    `${WP}/posts?slug=${slug}&_embed&_fields=title,content,date,_links`,
6    { next: { revalidate: 300 } }
7  );
8  if ( ! antwort.ok ) return null;
9  const treffer = await antwort.json();
10  return treffer[0] ?? null;
11}
12
13export async function generateStaticParams() {
14  const alle = await fetch( `${WP}/posts?per_page=100&_fields=slug` ).then( r => r.json() );
15  return alle.map( ( b: { slug: string } ) => ( { slug: b.slug } ) );
16}

3. Was verloren geht

Der Preis von Headless ist hoch, und er fällt vor allem im Alltag der Redaktion an. Der Website-Editor, Block-Muster, Stilvarianten und die Live-Vorschau beziehen sich auf ein Theme, das es nicht mehr gibt. Blöcke liefern HTML, das im Frontend eigene Stile braucht; dynamische Blöcke funktionieren nur, wenn das Frontend sie nachbaut. Plugins, die im Frontend arbeiten – Formulare, Cookie-Hinweise, SEO-Ausgaben, Caching –, wirken nicht mehr. Viele dieser Funktionen müssen im Frontend neu entstehen.

4. Betrieb

Beim Headless-Betrieb laufen zwei Systeme: WordPress, meist auf einer Subdomain wie cms.beispiel.de und für Suchmaschinen gesperrt, und das Frontend unter der eigentlichen Domain. Damit neue Inhalte zügig erscheinen, gibt es zwei Wege. Entweder das Frontend erneuert zwischengespeicherte Seiten nach einer festen Zeit, oder WordPress meldet sich beim Veröffentlichen über einen Webhook beim Frontend – die Brücke zur nächsten Lektion. Wichtig ist außerdem, den Zugriff auf die Schnittstelle abzusichern und im Kopf zu behalten, dass Weiterleitungen, Sitemap und robots.txt jetzt Sache des Frontends sind.

Typische Fallstricke im Betrieb

Drei Punkte kosten bei Headless-Projekten regelmäßig Zeit. Erstens die Zeichenkodierung und das gerenderte HTML: WordPress liefert Inhalte mit Umlaut-Entitäten und fertigen Blockklassen. Das Frontend muss beides behandeln – die Klassen brauchen eigene Stile, sonst sehen Spalten, Zitate und Buttons falsch aus. Zweitens die Bildpfade: Sie zeigen auf die WordPress-Domain, was funktioniert, aber die Bildoptimierung des Frontends umgeht. Drittens die Vorschau und das Zwischenspeichern: Wenn die Redaktion einen Beitrag ändert und fünf Minuten lang die alte Fassung sieht, entsteht schnell der Eindruck, das System sei kaputt. Ein Webhook, der die Seite sofort erneuert, löst das – und gehört von Anfang an dazu, nicht erst nach der ersten Beschwerde.

5. Ein Beispiel

Eine Sprachlern-Plattform betreibt eine Lern-App und einen Blog mit mehreren hundert Beiträgen. Das Frontend ist eine Next.js-Anwendung, WordPress läuft als reines Redaktionssystem auf einer Subdomain, gesperrt für Suchmaschinen. Beiträge werden beim Bauen abgerufen und alle fünf Minuten erneuert; beim Veröffentlichen löst ein Webhook zusätzlich eine sofortige Erneuerung aus. Formulare laufen über einen eigenen Endpunkt im Frontend. Die Redaktion arbeitet weiter im gewohnten Backend und merkt vom Aufbau nur eines: Die Vorschau öffnet eine besondere Adresse. Für diese Plattform lohnt sich der Aufwand – für die Website eines Handwerksbetriebs mit zwölf Seiten wäre er nicht zu rechtfertigen.

6. Häufige Fragen

REST oder GraphQL? Beides funktioniert. REST ist ohne Zusatzsoftware da und reicht für die meisten Projekte; GraphQL per Plugin ist praktisch, wenn viele verschachtelte Daten in einer Anfrage gebraucht werden, bringt aber eine weitere Abhängigkeit mit.

Wie funktioniert die Vorschau? Über einen geschützten Vorschaumodus im Frontend, der den Entwurf mit Anmeldung über die REST API holt. In WordPress wird die Vorschau-URL per Filter auf das Frontend umgebogen.

Ist Headless sicherer? Teilweise. Wenn WordPress nicht öffentlich erreichbar ist, sinkt die Angriffsfläche. Dafür kommt ein zweites System hinzu, das ebenfalls gepflegt werden muss.

7. Übung zum Selbermachen

Rufen Sie die REST API einer WordPress-Website mit ?_embed auf und suchen Sie in der Antwort die Adresse des Beitragsbilds sowie den Namen des Autors. Überlegen Sie anhand einer konkreten Website, welche Funktionen im Headless-Betrieb neu gebaut werden müssten: Welche Plugins wirken im Frontend? Wie viele Formulare gibt es? Wer pflegt die Layouts? Notieren Sie eine Empfehlung mit Begründung – diese Abwägung ist in der Praxis wertvoller als der technische Aufbau.

Stand: September 2026, WordPress 7.1, PHP 8.3. Kursmaterial der Klarwerk Akademie. WordPress entwickelt sich schnell – maßgeblich ist die aktuelle Dokumentation auf developer.wordpress.org.