Keeping WordPress for editors and replacing everything else
Headless WordPress is usually proposed because the front end needs to be something WordPress cannot be. The editing experience is worth keeping, and the cost of keeping it is a set of problems that only appear once the front end and the CMS are separate.
The CMS and the site are one system, and splitting them is the whole project
In ordinary WordPress the editor, the database, the templates and the rendered page are one application. Decoupling separates them: WordPress keeps the content and the editing, something else renders the pages, and the two communicate over an API. Everything that was implicit in them being one thing — previews, authentication, redirects, caching, search — becomes something that has to be designed.
- The front end needs to be a framework WordPress is not good at being
- Pages are being assembled from several systems and WordPress is only one of them
- The site has outgrown WordPress templates and customising the theme further is not viable
- Editors are happy with WordPress and there is no appetite for retraining them
- A framework front end is being considered and the content side has not been decided
- A previous decoupling attempt stalled on previews, redirects or caching
- Page delivery performance is the driver and template rendering is the constraint
- Content needs to be served to more than one surface — a site, an app, another product
The people who usually bring us this problem
A team whose front end has outgrown WordPress
The content side works and the delivery side has not kept up, and the editors would rather not change.
A team serving content to more than one surface
The same content has to reach a website, an application or another product, and one rendering path cannot serve all of them.
Someone whose previous decoupling stalled
Previews, redirects or caching did not survive the split, and the project stopped there.
What this costs while it goes unfixed
Engineering faults are rarely confined to the engineering layer. These are the commercial consequences we see most often.
Preview is the first thing to break
In ordinary WordPress an editor presses preview and sees the page, because the renderer and the editor are the same application. Once they are separate, preview has to be built — an authenticated path from the CMS to the frontend that renders a draft, and it is consistently the feature that decoupling projects discover late.
Redirects move out of the plugin that used to handle them
WordPress manages redirects through plugins that intercept the request before rendering. With a separate frontend, that request never reaches WordPress, so redirect handling has to be rebuilt where the routing actually happens. This is where search visibility is lost after a decoupling, and it is invisible until traffic drops.
Every page becomes a cache decision
A rendered page can be cached at the edge, at the origin, per-fragment, or not at all, and each choice has a different invalidation cost. Publishing has to propagate to whatever is cached, or editors publish and see the old page — which reads as the CMS being broken.
The search consequence is a design decision, not a deployment detail
A decoupled front end changes what the crawler receives, when content is reachable and whether anything is available without executing JavaScript. Whether that is an improvement depends entirely on how it is built, and it is not something to find out afterwards.
Capabilities
Each of these is work we carry out, not an area we advise on.
Content model and API design
What each content type exposes over the API, what shape the frontend receives, and what the frontend has to assemble itself. The API surface is the contract between the two systems, and decisions about it are what determine whether the frontend can render a page in one request or twenty.
The full request path, designed end to end
CMS, API, frontend rendering, cache layer and CDN as one path with defined behaviour at each step. Most decoupling problems are somewhere on this path, and the page's architecture section sets it out rather than leaving it to be discovered.
Preview and draft handling
An authenticated preview path so editors see a draft as it will appear, including for content assembled from more than one source. Built deliberately, because it does not exist by default and it is the first thing editors will ask for.
Redirect and routing ownership
Deciding where redirects, canonical URLs and 404 handling live once WordPress no longer serves the request, and implementing them there. This is the single largest search risk in a decoupling, and the one most often left unowned.
Caching and invalidation
What is cached where, how long for, and what happens on publish. Content propagation is a design decision made against how the site is edited, because an editor who publishes and does not see their change will treat the whole platform as unreliable.
Search-engine delivery
What crawlers receive at each step: server-rendered markup, hydration, structured data, sitemaps and internal linking. Decoupling can improve all of these or make them worse, and which one happens is decided in this work rather than measured after launch.
Editorial experience preservation
Keeping the editing workflow editors already know, and being honest where it changes. Blocks, taxonomies, media and revisions arrive over the API differently from how they render, and where an editor's habit has to change, that is planned with them rather than discovered by them.
Incremental migration of the existing front end
Moving routes across one at a time rather than replacing the site in one release, so the change is reviewable and reversible per route. A decoupling does not have to be a single cutover, and the risk profile is very different when it is not.
Engineering methodology
The sequence is deliberate. The order is usually what determines whether the work holds or has to be repeated.
Answer the preview question first
Before any frontend work, establish how an editor will preview a draft. It is the requirement that most constrains the architecture and it is the one most often raised after the build has started, at which point the options are expensive.
Decide where redirects, canonicals and 404s live
Written down, with an owner, before the frontend serves traffic. WordPress plugin redirects stop applying the moment WordPress stops receiving the request, and the gap is where a decoupling quietly loses its search visibility.
Design the request path before the page
CMS to API to frontend to cache to CDN, with each step's behaviour defined. Every later problem — a slow page, a stale page, a missing preview — resolves to a step on this path, so having it explicit is what makes the work diagnosable.
Treat caching as a content-lifecycle decision
Cache duration and invalidation are chosen against how the site is edited rather than against a generic best practice. A site with hourly publishing and a site with weekly publishing want different answers, and the wrong one shows up as editors distrusting the platform.
Migrate routes incrementally
Move one class of route across, verify it, then the next — with the old path still working throughout. This keeps the change reviewable, makes each step reversible, and means search consequences are attributable to a specific route rather than to a launch.
Check what a crawler actually receives
The rendered HTML, not the intended HTML. Server rendering, hydration timing, structured data, and whether anything important depends on JavaScript all get verified as delivered, because decoupling can improve all of them and it can break them silently.
Keep the editors informed of what changes
Some habits change. Where they do, that is agreed with the people who publish before the platform moves under them, rather than announced afterwards — a front end migration that degrades the editing experience will be judged on the editing experience.
What an engagement produces
Documentation is a deliverable, not an afterthought. On most of these engagements a large part of the value is a defect report precise enough for another team to act on.
Architecture
- Content model and API surface for every content type
- The request path end to end, with each step's defined behaviour
- Preview and draft handling, including for assembled content
- Where redirects, canonicals and 404 handling live, and who owns them
- Caching and invalidation strategy, chosen against the publishing pattern
- Which routes move and in what order
Build
- API layer over the existing content, without duplicating the content model
- Frontend rendering for the migrated route classes
- Authenticated preview path
- Redirects and routing implemented where requests actually arrive
- Cache invalidation wired to publish
- Search-engine delivery verified as received, not as intended
Handover
- Which routes are decoupled and which still render through WordPress
- What editors do differently, if anything
- Where to change a redirect, a canonical rule or a cache duration
- What was measured before and after, on both delivery and search
- The remaining routes and what migrating each would involve
Architecture and technology
The path a request takes
- The CMS — content, media and editorial workflow, unchanged for editors
- The API — what is exposed, in what shape, and what the frontend must assemble
- The frontend — rendering, routing and the redirect rules that used to live in WordPress
- The cache layer — what is cached where, and what invalidation reaches it
- The CDN — the edge that serves most requests and holds most of the copies
- The crawler's view — what is actually delivered before JavaScript runs
What decoupling takes away by default
- Preview, because the renderer is no longer the application the editor is in
- Redirects, because the plugin that handled them no longer sees the request
- Canonical URLs, unless the frontend generates them
- Sitemaps, unless something regenerates them from the API
- Internal link resolution, because content is stored as references that the frontend must resolve
- Authentication for anything previously behind WordPress's own session
If this is not quite your problem
These overlap at the edges. Sending you to the right page is more useful than having you work it out.
WordPress is being replaced rather than decoupled
The other fork in the road, and how to decide between them.
WordPress to Next.js migrationThe decoupled architecture more broadly
Choosing and building a decoupled stack, of which WordPress is one option.
Headless website developmentThe content is moving to a different CMS
Migration into a headless CMS, modelled before anything is moved.
Headless CMS migrationThe search consequences need handling
What a decoupled front end does to crawling, indexing and rendering.
JavaScript SEOFrequently asked
Do editors have to learn a new system?
That is the main reason to decouple WordPress rather than replace it — editors keep WordPress. Some things change: preview has to be reached through the path we build rather than the one they are used to, and where content is assembled from several sources the editing screen may not show the final composition. Those differences are agreed with the people who publish before the front end moves, because a decoupling that keeps WordPress and loses the editing experience has given up the thing it was for.
Will this help or hurt our search visibility?
It depends entirely on how it is built, which is why it is designed rather than measured afterwards. A decoupled front end can deliver marginally cleaner, faster server-rendered HTML, which is an improvement. It can equally drop the redirects that used to be handled by a WordPress plugin, make content unreachable without JavaScript, and change what a crawler sees at each step. The requirements are the same as any rendering change: what the crawler receives, whether redirects and canonicals survive, and whether anything important depends on client-side execution.
How does preview work when the front end is separate?
It has to be built, and it is the requirement that most constrains the architecture. WordPress's own preview shows a page because WordPress renders it; once something else renders, the edit screen has to reach an authenticated preview path on the frontend that renders the draft. Where content is assembled from more than one source, the preview shows the assembly the frontend would produce. We ask about this before proposing an architecture rather than after, because retrofitting it is expensive.
Does the whole site have to move at once?
No, and it usually should not. Routes can migrate one class at a time, with the ordinary WordPress rendering still serving everything not yet moved. That makes each step reviewable and reversible, keeps the search consequences attributable to a specific route rather than to a launch date, and avoids a single release that has to be right first time. It does mean both paths exist for a period, which is a real cost in complexity and is still worth paying.
Which framework should the front end use?
It follows from the requirements rather than from a preference, and the requirements that matter most are how the content is edited, whether preview matters, how much of the site is dynamic per visitor, and where caching needs to sit. A framework chosen before those are established is a decision that gets defended rather than evaluated. The architecture work starts by establishing them, and the framework recommendation comes out of that.
Related capabilities and work
Bring us the problem you have not been able to fix
Describe what is happening rather than what you think the cause is. If we are not the right people for it, we will say so.