Headless WordPress is one of those subjects where technical enthusiasm tends to run ahead of analysis. Decoupling is not an automatic improvement: it is a relocation of complexity, from plugin to code, from supplier to in-house team. This article gives as many reasons not to do it as reasons to do it, along with the two points on which projects actually run aground in practice: previewing drafts and rebuilding the SEO foundation.
What decoupling means
In a classic installation, WordPress stores the content, manages it and manufactures the pages the public sees. In a decoupled architecture, it keeps the first two roles and gives up the third. Another program fetches the content and builds the site, either in advance as static pages or on the fly on a server.
Two routes to the content exist side by side, and the choice between them has practical consequences.
- The REST API, built into the core of WordPress since version 4.7, in December 2016. Predictable, documented, available without installing anything. Its weakness is that it returns whole objects where you only wanted three fields, and forces several calls to put a complete page back together. The official REST API documentation gives the detail.
- GraphQL, through the WPGraphQL plugin, which became a canonical WordPress plugin in October 2024 when its author joined Automattic. It lets you ask for exactly the fields you want, nested the way the interface consumes them, in a single request.
A simple rule: start with the REST API, and move to GraphQL the day you find yourself writing three REST requests for what ought to be a single logical question.
The four good reasons to do it
- Performance on a content-rich site. The front end no longer computes anything on each visit: pages are produced once and served from an edge cache. On an editorial site with several thousand articles, the gap against a poorly cached classic WordPress is spectacular, and it shows up in the signals visitors actually perceive.
- A smaller exposed surface. The admin can live on a separate domain, filtered, even closed to the public. The bots that endlessly scan for admin paths find nothing left to chew on across the visible site.
- Reusing the content. The same body of content serves the website, a mobile app, an in-store display, a partner consuming a feed. It is the strongest argument, and the only one that justifies the investment on its own.
- Freedom to design the front end. No more theme constraints, no more compromises with a page builder. You build exactly the interface you want, with as lean a codebase as you choose.
The five reasons not to do it
- Previewing drafts becomes a building project. It is the first complaint of editorial teams, and by a long way. The “Preview” button no longer works on its own: you have to develop a preview route that fetches the authenticated draft and renders it in the real templates. Until that work is done, your writers publish blind.
- Plugins that produce output stop working. Forms, carousels, image viewers, share buttons, page builders: everything that generated HTML on the WordPress side has to be redone. SEO plugins go on storing the metadata, but they no longer display it: it is up to your front end to read it and write it into the page.
- Caching and cache invalidation become a permanent topic. You have to decide what triggers a rebuild, at what granularity, and how long it takes for a corrected typo to appear online. An honest answer to that last question separates the serious projects from the rest.
- Two foundations to maintain. WordPress and its plugins on one side, the front-end build chain and its dependencies on the other. Two update calendars, two vulnerability surfaces, two skill sets.
- Dependence on a developer grows. Changes the client used to make alone, adding a block, altering a layout, now call for a technical intervention and a deployment.
Decoupling is justified when the gain outweighs these five costs. Not before, and not because the architecture is elegant.
The front end: Astro or React, and why it is not the same decision
The two options answer two different needs, and confusing them is the most common mistake.
A mostly editorial site, where interactivity goes no further than a menu, a search box and a form, is best produced as static pages. Astro was designed for this case and documents its integration with WordPress (French-language page): JavaScript is sent only for the components that need it; the rest is plain HTML.
An interaction-heavy product, a personal account area, a dashboard, a configurator, belongs to a React application. The trade-off is well known: without server-side rendering, the content risks being seen neither by search engines nor by visitors on slow connections. Server-side rendering is therefore not a comfort option; it is a condition of visibility as soon as a page has to be indexed. If what you really need is a custom web application, the decoupling question becomes secondary: it is the application that structures the project.
The blind spot: SEO on a decoupled site
This is the part quotes most often forget, and it can be costed in full. In leaving the SEO plugins behind, you take back onto your own shoulders everything they produced in silence:
- Title tags and meta descriptions, page by page, archives and pagination included.
- Canonical URLs, without which paginated and filtered pages duplicate one another.
- An XML sitemap, kept up to date with every publication.
- Structured data: article, breadcrumb, organization, frequently asked questions.
- A syndication feed, still used by plenty of aggregators.
- A robots exclusion file and indexing tags, consistent across the two environments.
- A redirect plan, if the URLs change along the way.
- Handling of missing pages, with the right response code rather than an empty page served as a 200.
- Social sharing tags, which nobody generates any more.
Nothing insurmountable, but nothing free either: allow one to two weeks of dedicated work, and write it into the quote. A decoupled site poorly equipped on this front loses in visibility what it gains in speed, and the net result is negative. The technical foundations of SEO stay the same; they merely change hands, as do the actions that genuinely improve Google rankings.
What it costs in time
The orders of magnitude below apply to an existing, medium-sized editorial site migrated to a decoupled front end. They are expressed as workload, not as sums of money.
| Item | Indicative workload | Recurring? |
|---|---|---|
| Scoping and choice of architecture | 3 to 5 days | No |
| Build chain and deployment | 1 to 2 weeks | No |
| Rebuilding the SEO foundation | 1 to 2 weeks | No |
| Draft preview | 3 to 8 days | No |
| Rebuilding forms and front-end functions | 3 to 10 days | No |
| Training the editorial teams | 1 day | No |
| Maintaining two foundations | a few hours a month | Yes |
A single question really settles the debate, and it is not a technical one: does your company have lasting access to development skills? If the answer is no, decoupling will produce a fast site for eighteen months, then a site frozen solid that nobody dares touch any more.
Where we stand: prefer the gradual path
In the great majority of the cases we come across, the problem is not WordPress; it is the way it was built. A lighter theme, a decent page cache, reprocessed images and an edge cache in front of the site often deliver the speed gain being sought, for a fraction of the workload. WordPress remains a solid foundation when it is kept in good order, and the effect of speed on conversions can be had without changing architecture. Before deciding, it is worth comparing Astro and WordPress.
When that is no longer enough, we prefer to decouple a single section, the magazine or the catalog for instance, rather than the whole site. You measure the real gain, you learn the publishing chain on a limited perimeter, and you keep the option of stopping there. Extending it to the whole site is decided only afterwards, with figures in hand. Checking first whether the hosting is the real bottleneck, or putting an edge cache and filtering in front of the site, sometimes spares you the whole debate.
Frequently asked questions
Does decoupling improve SEO?
Indirectly, through speed and rendering stability. It can also damage it markedly if the technical elements are not rebuilt: titles, canonicals, sitemap, structured data and the handling of missing pages.
Can you keep a shop when you decouple?
Technically, yes: WooCommerce exposes its data through an API. But the checkout funnel, payments, taxes and shipping costs become a project in their own right, to be costed separately from the rest. The catalog side, for its part, is a solved problem: our Nalu theme, one of our Astro themes, reads the public WooCommerce Store API at build time, with no plugin and no key, and renders the departments, the filters, the variations and the product pages. That leaves the checkout itself to settle, which is the real question.
Will my writers see a preview?
Only if preview is explicitly developed, with a dedicated route that fetches the authenticated draft. It has to be budgeted from the outset, or the editorial team will be working blind.
Is it reversible?
Yes, and it is the main strength of this architecture: the content stays in WordPress, structured and exportable. Going back to a classic theme is work on the facade, not a data migration.
What to take away
Decouple when the content has to serve somewhere other than a single website, or when performance directly conditions turnover. In every other case, a well-built, well-cached WordPress is more than enough. Before any decision, have the real state of your site measured: half of all decoupling projects are settled by an audit and two days of optimization.
Read next: sustainable web design: how to build a light, fast site
Explore a decoupled architectureHave my current site audited
