Should You Go Headless With WordPress, or Leave It Behind?

Someone on the team proposes headless WordPress. The stated reason is usually performance, or React, or the fact that the theme has become a place nobody wants to work. Before anyone estimates it, ask a narrower question: which part of WordPress is the team actually trying to keep? That answer decides everything, because headless is a way of keeping exactly one part and discarding the rest.

Going headless with WordPress means you keep the editor, the roles and the content, and you throw away the theme layer that turns them into pages. The front end becomes a separate application that reads content over an API and renders it however it likes. Everything editors touch stays familiar. Everything visitors see is rebuilt from scratch.

Our position, stated up front so the rest of this can defend it: headless WordPress is a good answer to one specific question, and most teams asking for it are asking a different one. If the complaint is a slow, tangled front end, the theme is the problem and the theme is fixable. If the complaint is WordPress itself, headless keeps the thing you dislike and adds a second system to maintain. The band where headless genuinely wins is real but narrow, and it is worth being able to recognise from the outside.

What going headless actually changes

In a headless setup, WordPress stops being a website and becomes two things: an administration screen and a content service. Pages are requested from a separate front end, usually over the REST API or a GraphQL layer sitting on top of it. The PHP that used to assemble the HTML never runs where the public can reach it.

What survives the move

• The editing interface. Writers keep the screen they know, the media library they have filled, and the drafts they have half-finished. This is the single strongest argument for headless and it should not be dismissed.
• Roles, capabilities and revisions. Who may publish, who may only draft, and what the previous wording was: all of it is untouched, because none of it lives in the theme.
• The content model. Post types, taxonomies and custom fields carry over, assuming they were registered properly rather than assembled inside a builder.
• Back-office plugins. Anything that only affects the admin experience keeps working, since the admin is still ordinary WordPress.

What stops working

Everything downstream of the theme. Template files, the template hierarchy, widgets, menus as rendered output, shortcodes, and any plugin whose value is that it prints something on the front end. A related-posts plugin no longer has a page to print into. A cookie banner plugin has no head to inject. A caching plugin is caching a page nobody visits.

That is not a bug in the approach. It is the approach. You are buying a front end you fully control by giving up the front end WordPress gave you for free, along with the twenty years of plugin ecosystem that assumed it existed.

What you gain, stated without the sales pitch

The performance ceiling rises. A themed WordPress page assembles itself per request unless something in front of it prevents that; a decoupled front end can be built once, cached at the edge and served as static HTML with a small amount of JavaScript. You are not promised a faster site. You are given the ability to build one, which is a different and more honest claim, and it is only worth something if someone on the team knows how to spend it.

The public attack surface shrinks. Nothing on the open internet executes PHP or reaches the database directly. Login sits on an origin you can restrict by network. That does not make the site secure, because a badly written front end can leak plenty on its own, but it removes an entire category of the automated scanning that WordPress installations attract by virtue of being WordPress.

And the front end becomes ordinary application work. It can be tested, reviewed, typed, componentised and deployed on its own cadence, by people who never open the admin. If you are already running application-shaped features alongside the marketing pages, that consolidation is the real prize: one front end, one deployment story, two content sources behind it.

One more that gets undersold: several surfaces can read the same content. A website, a mobile app, an in-store screen and a partner feed all consuming one editorial source is a genuinely good reason to decouple, and it is the reason least likely to change its mind in eighteen months.

What breaks on day one

Preview

This is the one that decides whether the project is adopted or resented. In themed WordPress, preview is free and immediate: the same code renders the draft that renders the published page. In a headless setup, preview has to be built. The front end needs an authenticated route that fetches unpublished content, the editor needs a button that lands there, and the whole path needs to work for a writer who is not on the office network at ten at night.

It is solvable. Every serious headless project solves it. But it is a feature with a cost, it is usually scoped late, and until it works your editors are publishing blind, which they will describe to their manager in exactly those words.

Plugins and page builders

Page builders do not survive. Their output is bound to their own rendering engine, so a builder-heavy site is not a headless candidate; it is a rebuild wearing a smaller word. The same applies to any layout assembled from shortcodes. If your pages are built that way, read the trade-offs in Gutenberg, page builders or custom blocks first, because that decision sits upstream of this one and it is where the real lock-in lives.

Block content is better placed. Blocks serialise into structured markup, and a front end can map known blocks to its own components. Known ones. Every custom block, every third-party block and every block pattern needs a component on the other side, and someone has to keep the two lists in step forever.

The long tail nobody scopes

Forms. Site search. Redirects. XML sitemaps. Canonical tags and metadata that used to come from an SEO plugin. Comments, if you have them. Pagination and archive pages. The 404. Feeds. Each one was a checkbox in the old stack and is now a small piece of engineering, and collectively they are usually larger than the homepage everyone is excited about.

This is also where the failure mode of the whole model shows up. The reason a marketing team ends up asking a developer for small changes is that the editable surface quietly shrank. Headless shrinks it by default, unless you deliberately model the parts editors need to control: navigation, promotional banners, footer links, the wording on a form. Model them, or you have handed the team a beautiful site they must file a ticket to change.

The cost that never makes it into the quote

You now run two systems. WordPress still needs updating, hardening, backing up and monitoring, exactly as before, and it has gained a new job as an API whose uptime the public site depends on at build time. The front end needs its own hosting, its own build pipeline, its own dependency updates and its own error monitoring. Nothing about the first system got smaller.

That reshapes the support arrangement, and it is worth being blunt about it while the estimate is being written. A retainer that used to cover plugin updates and a monthly backup restore test now covers two release trains. If you are unsure what yours currently includes, what a maintenance retainer actually buys is the more useful thing to read before adding a second stack to it, and ongoing maintenance should be priced as part of the decision rather than after it.

There is a hiring consequence too. A themed WordPress site can be maintained by a broad pool of people. A decoupled front end needs someone comfortable with a JavaScript build, a rendering strategy, cache invalidation and a deployment platform. That person is not rare, but they are a different person, and if they leave you cannot replace them with the agency that has been doing your plugin updates.

Three options, compared honestly

Most of these conversations get framed as headless or nothing. There are three doors, and the middle one is the door teams skip: keep WordPress, and fix the theme properly.

Read the "systems to maintain" row twice. It is the row that ends most headless proposals in organisations without a standing engineering team, and it is almost never the row on the slide.

When headless earns its keep

Here is the honest concession, because the argument so far has been one-sided. There are situations where we would go headless without much hesitation, and they share a shape: the editorial team must stay put and the front end must go somewhere WordPress cannot follow. A large archive with real search equity, editors who publish daily and have no appetite for a new tool, and a product surface that needs to render that content inside an application. That is a genuine fit, and replatforming it would be reckless.

Commerce is the other case, and the sharpest one. A catalogue that outgrows what the theme can render, with checkout, search and merchandising all competing for the same request, is a legitimate reason to decouple. The strain patterns are described in WooCommerce at scale, and they show up long before anyone calls the site large. Note the condition attached, though: decoupling helps when the bottleneck is rendering. It does nothing at all when the bottleneck is the database, and telling those two apart is the first hour of the investigation.

Decouple when the front end has somewhere else to be. Not when the theme is simply badly written, because that is a smaller and cheaper problem wearing an expensive disguise.

The case for leaving instead

If you are already prepared to rebuild the entire front end, you have accepted most of the cost of a migration. At that point the question deserves asking plainly: what is WordPress still doing for you? If the answer is the editing experience and the archive, keep it and go headless. If the answer is habit, leaving is cheaper than it looks, because the expensive half of the work was on the table either way.

The thing that decides whether a move holds is not the new platform. It is the URL inventory and the redirect map. The sequence is written out in migrating off WordPress without losing rankings, and the same discipline governs a headless cutover, where the URLs change less but the rendering changes completely. Either way it is the same body of migration work, run with the same care.

Replatforming also lets you choose where content sits rather than inheriting it. A structured workspace like Acrosite takes one of the available shapes: editors work in structured fields, the workspace generates the files, commits them to GitHub and triggers the configured deployment, so the content history and the code history are one history. Our parent company has written about the related question of where drafts live and what stops them, which is usually the complaint sitting underneath a platform complaint.

The order we would run this decision

Do these in sequence. Most teams stop at step three with a cheaper answer than the one they walked in with.

1. Write down the actual complaint. Slow pages, painful publishing, a theme nobody can safely edit, or a front end that needs to be an application. Those are four different problems with four different fixes, and only one of them is headless.
2. Measure the front end before you blame it. Field data on the pages that matter, not a lab score on the homepage. A theme with a rendering problem and a site with a hosting problem look identical from the outside and cost very different amounts to fix.
3. Inventory every plugin that renders something. Forms, SEO output, sitemaps, redirects, galleries, banners, consent. Each survivor becomes a line item on the other side. This list is the estimate.
4. Name who owns the front end afterwards. A named person or team with the skills, not a hope that the agency will pick it up. If you cannot name them, stop here.
5. Price preview, editable regions and the long tail explicitly. Then compare that number against fixing the theme, and against leaving. Now you have a decision instead of a preference.

Where we would start

For a marketing site with a small team, a builder-shaped history and a front end that is merely untidy: stay, and rebuild the theme properly with block-based templates. It is unglamorous, it is reversible, and it removes the actual pain at a fraction of the cost. Most sites that arrive asking about headless belong here.

For a publisher with a deep archive, daily editors and a front end that has to behave like an application: headless, with preview and editable regions built in the first release rather than the last. Budget the second system honestly and name its owner before the kick-off, not after.

And if what you really want is out, go out deliberately and take the redirect map seriously. Whichever door you pick, decide it with the plugin inventory and the maintenance cost in front of you, because those are the two documents that make the choice obvious. If you would like a second read on a specific installation, tell us what you are running and where it hurts.