Headless-Migrationen sehen auf dem Architektur-Bild elegant aus. WordPress als Backend, Next.js als Frontend, dazwischen eine saubere API — eine klare Trennung, die jedem CTO einleuchtet. In der Praxis stolpern dieselben Migrationen aber über fünf wiederkehrende Muster, und wir haben jedes davon mindestens einmal in eigenen Schweizer Projekten zwischen 2024 und 2026 gesehen. Vier dieser Muster lassen sich vor dem Migrationsstart im Audit erkennen — der fünfte zeigt sich erst, wenn echter Traffic auf die neue Architektur trifft. Wer die eigene Ausgangslage einordnen will, bekommt mit dem kostenlosen Website-Check als Audit-Vorstufe in unter einer Minute eine erste Einschätzung.
Die folgende Aufstellung ist bewusst nüchtern. Keine spektakulären Storys, keine Namen, keine erfundenen Zahlen — nur die fünf Muster, die in eigenen Projekten und in dokumentierten Branchenanalysen immer wieder auftauchen. Wer eine Migration plant, kennt diese Punkte besser vor der Offerte als nach dem Launch.
Warum ist die Preview bei Headless WordPress oft kaputt?
Die Preview-Funktion bricht, weil WordPress' Vorschau-Mechanik an das aktive Theme gekoppelt ist — und im Headless-Setup gibt es kein aktives Theme mehr. Ohne eine eigene Preview-Schnittstelle sehen Editor:innen statt ihres Entwurfs eine leere Seite, eine 404 oder die alte Theme-Vorschau. Das ist die am häufigsten unterschätzte Stolperfalle.
Was passiert: Eine Redaktorin schreibt einen Artikel-Entwurf, klickt auf "Vorschau" — und sieht entweder eine leere Seite, eine 404-Antwort oder die alte Theme-Vorschau, die mit der neuen Headless-Site nichts mehr zu tun hat. Beim ersten Stakeholder-Review schlägt das durch: Der Beitrag ist da, ist aber nicht zeigbar. Vertrauen in das System bricht in dieser Minute weg, und es lässt sich später nur schwer zurückgewinnen.
Warum das passiert: WordPress' Preview-Mechanik ist tief mit dem klassischen Theme-System verwoben. Im klassischen Setup rendert WordPress den Draft im aktiven Theme — fertig. Im Headless-Setup gibt es kein aktives Theme mehr. Stattdessen braucht es eine eigene Preview-Schnittstelle: eine Custom-Endpoint, die unveröffentlichte Slugs ausliefert, plus Frontend-Routing, das Preview-Tokens akzeptiert und damit autorisierte Drafts im Next.js-Layer rendert. WPGraphQL Smart Cache hat dafür inzwischen ein etabliertes Muster, aber Plumbing bleibt es. Plug-and-play ist es nicht.
Frühwarnsignal im Audit: Wenn die bestehende Site Custom-Block-Patterns oder eigene Gutenberg-Blocks im Editor nutzt, ist Preview-Plumbing fast garantiert ein Eigenbau-Posten — die Custom-Blocks müssen im Frontend gerendert werden können, bevor sie veröffentlicht sind. Bei reinen Standard-Block-Setups ist der Aufwand kleiner, aber nie null. Wer das Preview-Setup erst nach dem Migrationsstart angeht, riskiert eine Phase, in der das System technisch fertig ist, redaktionell aber noch nicht produktiv arbeitet.
Welche Plugins funktionieren headless nicht mehr?
Frontend-aktive Plugins funktionieren headless nicht automatisch weiter — alles, was im klassischen Setup HTML, CSS oder JavaScript in die Seite gerendert hat (Yoast-Meta-Ausgabe, Slider, Form-Builder, Page-Builder-Blocks), braucht eine Frontend-Replika oder einen Ersatz. Plugins, die nur Daten liefern, lassen sich über REST oder GraphQL weiterhin konsumieren. Diese Trennung ist die teuerste Überraschung im Projekt.
Was passiert: Yoast SEO erzeugt im klassischen Theme-Output strukturierte Daten und Meta-Tags direkt im <head> der Seite. Im Headless-Setup gibt es diesen <head> so nicht mehr — der Frontend-Code muss die Yoast-Werte explizit auslesen und im Next.js-Layer in Metadata, Schema und Open-Graph-Tags umsetzen. Das gleiche gilt für Slider-Plugins, Form-Builder, Page-Builder-Blocks und alles, was im klassischen Setup direkt HTML, CSS oder JavaScript in die Seite gerendert hat: Frontend-aktive Plugins sind im Headless-Setup neu zu bauen oder zu ersetzen.
Warum das passiert: Plugins waren historisch theme-gekoppelt. Die Trennung zwischen Backend und Frontend bedeutet, dass jede Plugin-Wirkung, die auf der Seite sichtbar war, eine Frontend-Replika braucht. Manche Plugins liefern dafür eine saubere REST- oder GraphQL-Schnittstelle (Yoast über das wpseo-Schema-Feld in WPGraphQL etwa), andere bieten gar keine API und müssen komplett ersetzt werden. Branchenanalysen wie die WP-zu-Headless-Retrospektive von FocusReactive nennen 2 bis 3 zusätzliche Entwickler:innen für die "Feature-Parität" mit klassischem WordPress als typische Konsequenz — gerade bei Sites mit gewachsenem Plugin-Stack.
Frühwarnsignal im Audit: Plugin-Inventar mit mehr als acht frontend-aktiven Plugins ist ein roter Indikator. Pro Plugin lohnt eine kurze Klassifizierung in drei Kategorien — Daten liefernd, UI rendernd oder an Theme-Hooks hängend. Diese drei Kategorien lassen sich in einem 30-minütigen Workshop sauber kartieren — und sie sparen später Tagessätze.
| Plugin-Kategorie | Verhalten im klassischen Setup | Headless-Aufwand |
|---|---|---|
| Daten-Plugin (z. B. ACF, Yoast-Meta) | Liefert Felder/Werte, rendert kein eigenes UI | Niedrig — über REST/GraphQL konsumierbar |
| UI-Plugin (Slider, Form-Builder, Galerie) | Rendert HTML/CSS/JS direkt in die Seite | Mittel bis hoch — Frontend-Replika nötig |
| Theme-Hook-Plugin (Page-Builder, Widgets) | Hängt an Theme-Hooks und Templates | Hoch — meist komplett zu ersetzen |
Ein Sonderfall verdient frühe Aufmerksamkeit: Plugins, die Daten ans Frontend durchreichen, vergrössern die Angriffsfläche, wenn Tokens oder Felder ungefiltert im Client-Bundle landen. Wie sich die Angriffsfläche bei Headless WordPress gegenüber dem klassischen Monolithen verschiebt, behandeln wir im dedizierten Sicherheits-Beitrag — die Plugin-Klassifizierung im Audit ist auch dort der erste Schritt.
Warum bricht die REST-API unter Last ein?
Die ungecachete WordPress-REST-API bricht unter Last ein, weil jeder Request den vollen WordPress-Stack durchläuft — PHP-Init, Plugin-Loading, Datenbank-Queries, Hook-Filter. Eine uncachete WordPress-Antwort liegt typischerweise bei 500 bis über 2'000 ms TTFB, edge-gecachet dagegen bei 5 bis 30 ms (FatLab, 2025). Im Headless-Setup ist die API der einzige Backend-Kontakt — wird sie nicht separat gecachet, wird sie zum Flaschenhals.
Was passiert: Eine ungecachete WordPress-REST-API hat pro Request den vollen WordPress-Stack im Pfad: PHP-Initialisierung, Plugin-Loading, Datenbank-Queries, Hook-Filter. Unter Last — eine Marketing-Kampagne geht live, ein Blogpost wird auf LinkedIn geteilt, ein Suchmaschinen-Crawl läuft durch — wird die API zum Bottleneck. Antwortzeiten steigen, im schlimmsten Fall liefert das Backend gar keine Antwort mehr. Das Frontend-CDN bleibt verfügbar, aber für jede Seite, die nicht im Cache liegt, läuft die Anfrage durch zur überlasteten API.
Warum das passiert: Klassisches WordPress hat den Cache typischerweise vor dem Theme — Page-Cache via WP-Rocket, Cloudflare-Cache vor der Origin. Die REST-API umgeht diese Cache-Schicht, weil sie nicht denselben URL-Pfad nutzt wie eine Theme-Seite. Wer die Cache-Konfiguration vom klassischen Setup übernimmt, schützt nur das Theme — nicht die API, die jetzt der einzige Kontakt zwischen Frontend und Backend ist. Eine vertiefte Einordnung dazu, wie Cache-Strategie und Web-Vitals zusammenhängen, finden Sie im Beitrag zu Core Web Vitals und WordPress 2026.
Mitigation: Drei Pfade haben sich bewährt. Erstens ISR mit On-Demand-Revalidierung — Next.js 16 macht das nativ, Inhalte werden bei Speicherung im WordPress per Webhook revalidiert, das Frontend-CDN serviert die meisten Anfragen aus dem Cache. Zweitens ein API-Layer-Cache (Redis oder vergleichbar) zwischen REST und Frontend. Drittens GraphQL-Cache via WPGraphQL Smart Cache. Wir setzen typischerweise auf den ISR-Pfad, weil er ohne zusätzliche Infrastruktur auskommt. Frühwarnsignal: Wenn die Frage "wie viele REST- oder GraphQL-Calls fallen pro Page-Load an?" im Audit nicht beantwortbar ist, ist die Antwort wahrscheinlich "zu viele". Sichtbar wird das aber meist erst beim ersten echten Lasttest.
Wie werden Gutenberg-Blocks im Headless-Frontend gerendert?
Gutenberg-Blocks müssen im Headless-Frontend aktiv geparst und in React-Komponenten übersetzt werden — sie liegen in WordPress als HTML-Kommentar-Marker im post_content, nicht als fertiges HTML. Standard-Blocks (Paragraph, Heading, Image) lassen sich günstig mappen; Custom- und Reusable Blocks brauchen eigene Parser. Es gibt dafür keine kanonische Core-Pipeline, nur konkurrierende Bibliotheken.
Was passiert: Gutenberg-Blocks werden in WordPress als HTML-Kommentare im post_content gespeichert — ein Paragraph etwa als <!-- wp:paragraph --> plus Inhalt plus <!-- /wp:paragraph -->. Beim Headless-Konsum muss das Frontend diese Kommentar-Marker parsen und die Blocks in eigene React-Komponenten übersetzen. Wer das nicht plant, stellt im Migrationsprojekt fest, dass post_content zwar wie HTML aussieht, aber alles andere als sauber gerendertes HTML ist.
Warum das passiert: Es gibt keine kanonische "Block-zu-React-JSX"-Pipeline aus dem WordPress-Core. Es existieren mehrere Konkurrenten-Bibliotheken — @wordpress/block-serialization-default-parser aus dem Core, kommerzielle Lösungen wie wp-block-to-html —, aber keine breit etablierte Convention. Standard-Blocks (Paragraph, Heading, Image, Columns, List) lassen sich relativ günstig mappen, weil ihre Struktur klar dokumentiert ist. Custom-Blocks und Reusable Blocks brauchen Custom-Parser, oft pro Block-Typ einzeln gepflegt.
Mitigation: Block-Inventar im Audit. Eine kurze Tabelle mit allen verwendeten Block-Typen, gegliedert nach Aufwand und Audit-Signal:
| Block-Typ | Headless-Aufwand | Audit-Signal |
|---|---|---|
| Standard (Paragraph, Heading, Image, Columns, List) | Niedrig — klar dokumentiert, günstig zu mappen | Unkritisch |
| Custom (eigene Block-Typen) | Mittel — Tagessatz pro Block-Typ | Mehr als 5 Custom-Block-Patterns = Aufwandstreiber |
| Reusable (wiederverwendbare Blöcke) | Hoch — Sonderfall, oft mehrere Tagessätze | Aktives Block-Pattern-Setup im Theme |
Wer das Inventar vor dem Migrationsstart kennt, hat keinen Überraschungsposten in der Schlussrechnung. Frühwarnsignal: mehr als fünf Custom-Block-Patterns im bestehenden Setup oder ein aktives Block-Pattern-Setup im Theme. Beides bedeutet zusätzliche Frontend-Komponenten, die ohne saubere Inventarisierung leicht zu Tagessatz-Drift führen.
Warum kollidieren CMS- und Frontend-Deploy beim Mismatch?
CMS- und Frontend-Deploy kollidieren, weil beide Pipelines unterschiedlich getaktet sind: WordPress wird klassisch deployed (FTP, SSH, WP-CLI, Admin-Updates), das Frontend per Git-Push mit automatischem Build. Ohne Koordination geht das Frontend mit alten Daten live, oder ein in WordPress aktivierter Custom-Block trifft auf einen Frontend, der den zugehörigen Renderer noch nicht kennt. Die Mitigation ist organisatorisch wie technisch.
Was passiert: WordPress wird klassisch deployed — FTP, SSH, WP-CLI, manuelle Plugin-Updates über das Admin-Interface. Das Frontend wird per Git-Push zu Vercel, Cloudflare Pages oder Netlify deployed, mit automatischem Build und Preview-Deployment pro Pull-Request. Wenn beide Pipelines nicht koordiniert sind, geht das Frontend mit alten Daten live, oder das Backend produziert Inhalte, die das Frontend (noch) nicht versteht — ein neuer Custom-Block, der in WordPress aktiviert wird, bevor der zugehörige Frontend-Renderer deployed ist.
Warum das passiert: Frontend-Schema-Veränderungen — eine neue ACF-Field-Group, ein neues Block-Pattern, eine neue Custom-Post-Type-Konfiguration — brauchen einen koordinierten Deploy. Ohne Pipeline-Convention kommt es zu Lücken: Das Backend-Team aktiviert Plugins über das Admin-UI, das Frontend-Team kennt diese Änderung nur durch Zufall. Mitigation ist organisatorisch wie technisch zugleich. Deploy-Reihenfolge dokumentieren, idealerweise als Runbook. Schema-Versionierung im WordPress-Backend als Code in mu-plugins/ ablegen statt nur in der Datenbank. Frontend-Build mit Schema-Snapshot, der bei Mismatch laut wird. Webhooks zwischen WordPress-Save und Frontend-Revalidierung, damit Content-Updates nicht in einem Cache-Fenster verschwinden.
In diesem Kontext lohnt ein kurzer Blick auf die strategische Plattform-Wahl: WPGraphQL erscheint seit Januar 2026 als Monorepo mit regelmässigen Releases, zählt laut WordPress-Plugin-Verzeichnis über 30'000 aktive Installationen (Stand Juni 2026), und Maintainer Jason Bahl ist seit Oktober 2024 bei Automattic — WPGraphQL bewegt sich damit in Richtung kanonisches WordPress-Plugin. Das senkt das Vendor-Lock-in-Risiko bei der API-Wahl, ohne es ganz zu eliminieren. Frühwarnsignal: Wenn das aktuelle WordPress keine versionierten Plugin-Konfigurationen oder ACF-Felder im Code hat, sondern nur in der Datenbank, ist die Pipeline-Diskussion eine eigene Phase im Projekt — nicht ein Nebenposten.
Vier von fünf Stolperfallen sind im Audit erkennbar — wer ohne Audit migriert, lernt sie unter Last.
Wie lange dauert eine Headless-WordPress-Migration?
Eine Headless-WordPress-Migration dauert in eigenen Schweizer Projekten 2024–2026 typischerweise zwischen 6 und 16 Wochen — abhängig vom Plugin-Stack, der Anzahl Custom-Blocks und davon, ob Preview und Deploy-Pipeline sauber vorbereitet sind. Die Audit-Vorstufe selbst braucht 1 bis 3 Wochen; sie verschiebt die teuren Überraschungen aus der Bauphase in die Planung. Branchenanalysen wie die WP-zu-Headless-Retrospektive von FocusReactive nennen 2 bis 3 zusätzliche Entwickler:innen für die Feature-Parität als typischen Aufwandstreiber.
Die konkreten Budgetstufen — und welche der drei Treiber (Mehrsprachigkeit, SEO-Setup, laufender Betrieb) den Preis bewegen — behandeln wir nicht hier, sondern im Beitrag zu Headless-WordPress-Kosten 2026 mit drei Budgetstufen. Dieser Beitrag besitzt die Kostenfrage; wir verweisen bewusst darauf, statt sie doppelt zu beantworten.
Bleiben SEO-Rankings bei der Migration erhalten?
SEO-Rankings bleiben bei einer sauber geplanten Headless-Migration erhalten — vorausgesetzt, die URL-Struktur wird 1:1 übernommen oder per 301-Redirect-Map abgebildet, und die Yoast-Meta-Ausgabe wird im Frontend korrekt rekonstruiert. Der häufigste Ranking-Verlust entsteht nicht durch Headless an sich, sondern durch unbeachtete URL-Wechsel beim Cutover und fehlende Meta-Tags im neuen Frontend. Beides gehört in die Audit-Phase, nicht in die Launch-Woche.
Der URL-Redirect-Cutover ist dabei ein eigener Prüfpunkt: Jede alte URL braucht entweder dieselbe Route im neuen Frontend oder einen 301-Redirect auf das passende neue Ziel. Eine vollständige Redirect-Map vor dem Go-Live verhindert die 404-Welle, die Crawler und Rankings am stärksten trifft.
Was wir bei der nächsten Migration anders machen
Drei Anpassungen haben sich in den eigenen Projekten zwischen 2024 und 2026 wiederholt als sinnvoll erwiesen. Erstens: Preview-Setup als erstes Akzeptanz-Kriterium im Pflichtenheft, vor Performance-Zielen, vor SEO-Setup, vor Designsystem. Wenn die Redaktion ihr eigenes System nicht bedienen kann, ist alles andere nachrangig. Zweitens: Plugin-Inventar mit Frontend-Aktivitäts-Klassifizierung vor Migrationsstart — die drei Kategorien "liefert Daten / rendert UI / hängt an Theme-Hooks" sind die einfachste belastbare Heuristik, die wir bisher gefunden haben. Drittens: Lasttest-Profil im Audit definieren, nicht erst kurz vor Launch. Welche Last erwartet die Site realistischerweise im ersten Quartal nach Launch? Aus welchen Quellen, mit welchen URL-Mustern? Diese Frage gehört in die Audit-Phase, nicht in die letzte Sprint-Woche.
Wer diesen Anpassungen folgt, eliminiert die Stolperfallen nicht — er verschiebt sie in eine Phase, in der sie noch billig zu beheben sind. Genau darum geht es bei einer ehrlichen Audit-Vorstufe: nicht jedes Risiko wegplanen, sondern die teuren Risiken früh sichtbar machen. Eine Übersicht über das gesamte Vorgehen finden Sie auf der Leistungen-Seite mit Audit-, Migrations- und Skalierungs-Paketen.
Nächster Schritt
Wenn Sie wissen wollen, wo Ihre Site bei Performance, SEO und Architektur aktuell steht, ist der schnellste Weg ein Blick von aussen. Mit dem Website-Check als kostenlose Audit-Vorstufe sehen Sie in unter einer Minute, wo die grössten Hebel liegen — und welche der fünf Stolperfallen für Ihr Setup relevant werden könnten. Eine vertiefte Einordnung der Investitionskosten liefert der Beitrag zu Headless-WordPress-Kosten 2026 mit drei Budgetstufen, eine vertiefte Einordnung der strategischen Vorteile finden Sie im Beitrag Headless WordPress: 5 Vorteile für wachstumsorientierte Unternehmen.
Wenn Sie die nächsten Schritte direkt besprechen wollen, vereinbaren wir gerne ein Erstgespräch — 15 Minuten, kostenlos. In dieser Zeit klären wir Ausgangslage, Ziele und passende Migrations-Stufe — und Sie wissen am Ende, ob Ihre eigene Migration über eine der fünf Stolperfallen führen würde, bevor Sie das Budget freigeben.