Don’t let anyone tell you the hard part of a headless WordPress is linking up Next.js to the REST API. You can have a tutorial for that done in an afternoon. The difficulty comes in after you have launched: putting together preview workflows your editors will put their faith in, making schema changes without breaking the frontend in some silent way, and being left to maintain a Gutenberg block layer in perpetuity. Then there is the admin panel which has no resemblance to the public site. These are the things most “should we go headless” arguments overlook, only to be confronted with them down the road.
So if you are considering a WordPress headless CMS, asking if it is technically feasible is the wrong question. Of course it is. The one you should be asking is whether the benefits on the frontend or across channels are worth the price of owning a second platform in the long run. We put this guide together for teams wanting to make an honest call before the architecture becomes a maintenance bill.
What Headless WordPress Actually Means
On a standard WordPress site, the process does double duty: it holds your content and renders the pages via a PHP theme. With headless you divide and conquer. WordPress is left to its job of managing content while a distinct frontend – typically something like Next.js – pulls from the REST API or WPGraphQL and puts the site in front of the public.
It has been a supported option since the REST API was put into core back in December 2016, but don’t mistake it for the mainline path. WordPress development is still very much about the block editor, Full Site Editing and PHP themes. Automattic’s own take on headless will tell you that recent work on the Interactivity API and the block editor has made decoupling less of a necessity in some cases. It is important to understand that as a headless user you are on a second-class track in a platform whose core team is investing its time elsewhere. It all works fine, but the framing is there for a reason.
What you keep, what you give up
You get to hold onto the WordPress admin, the block editor, user roles and the publishing workflow your team is used to. But you are losing the WYSIWYG at the theme level and a live “view post” that is an accurate reflection of production. A lot of plugins won’t work anymore either because they need to render into a theme – think related-post widgets, form plugins, Yoast’s frontend side of things or A/B testing UIs. You can cobble some of it back together with custom code, but not all of it.
Why Teams Reach For It
Usually the headless talk is born of frustration rather than some preference for the architecture. Pressable’s overview is clear on the usual suspects: security, performance and the latitude to use modern frameworks. In the end the business case for it boils down to one of three things:
- Multiple delivery surfaces. You have one CMS but you need the same content to feed a partner, a mobile app, a product area for logged-in users and your marketing site.
- The frontend has outgrown the theme. Your product people are trying to build commerce flows or interactive components that a page builder simply can’t handle with any neatness.
- Performance is tied to the bottom line. Core Web Vitals are hurting your conversion or rankings and you have already done all you can with caching and plugin pruning.
If you don’t have those, you are likely solving the wrong problem. Even WP Engine, WordPress’s enterprise host, will make that point. Their guide will show you the security and performance upside but also note that you can get there by optimising a traditional build. Put a custom theme on managed hosting with a good caching layer and it will beat a shoddy headless implementation every time.
The Parts Tutorials Skip Over
The tutorials showing you how to connect to /wp-json are fine. They are accurate. But they only cover the easy 20 per cent. The rest is where you will see projects go over budget or quietly fold.
Preview is harder than it sounds
Traditionally an editor clicks “Preview” and there is the draft on the live theme. In a headless world that button has to reach out to another system. You need a signed token from WordPress, a separate cache rule so the editor isn’t looking at yesterday’s version, a dedicated route on the frontend and a fetch that is draft-aware and doesn’t hit the public CDN. People consistently underestimate this. When it doesn’t work right, editors lose confidence in the preview and want to go back to the old admin. That costs you credibility.
Gutenberg stores HTML, not clean JSON
There is no versioned, structured JSON for a full post that is officially sanctioned. What the block editor saves is HTML with comment delimiters to mark off the blocks.
When headless consumers go to parse block comments and put their own spin on block rendering in the frontend, you are left with a compatibility layer of your own making. It is one you will have to maintain in step with whatever Gutenberg throws at you, meaning every core update carries some risk of regression.Schema drift has a price
Let someone add a field in Advanced Custom Fields or tinker with a custom post type and the frontend may well break without fanfare. WordPress is a database with a CMS bolted on top, and the REST API puts that structure on display for any frontend to consume. In a mature headless environment you don’t let that happen; you interpose a versioned API (a Node or GraphQL service will do) to normalize the shapes and treat WordPress as an internal matter, not a public API.
The REST API is no public surface
Then there is authentication, which tends to be a surprise. For logged-in users the REST API is dependent on nonces and cookie auth. Application Passwords are fine for server-to-server but they are tied to user accounts. You need plugins for JWT or OAuth. Most teams in production make the right call and put WordPress behind a private network where only the SSR server or build pipeline can see it, but that is infrastructure work that was never in the budget.
Database build pressure
Your static site generation is running smoothly until the build job starts churning through /wp-json/wp/v2/posts?per_page=100 and the database is locked up for forty minutes. The default REST shapes are handy enough but they were not made for high-frequency batch reads. To run headless WordPress at scale you will find you need a read replica, some custom endpoints that are cache-friendly, or throttled builds.
An honest look at the ROI
If you want a clear timeline, look at the numbers from agency Pagepro on their headless migrations from monolithic WordPress. Their case work shows a consistent pattern:
| Phase | What happens |
|---|---|
| 0 to 3 months | You are in the red. Between the migration costs and the learning curve, editorial productivity takes a hit as you put new workflows in place. |
| 3 to 9 months | Things stabilize. You get faster publishing and iteration on the frontend, and you can measure an improvement in Core Web Vitals. |
| 9 to 24 months | For mid-sized teams that put money into content modeling and training, not just engineering, the ROI turns positive. |
But the telling part of the analysis is what separates the winners. ROI is a function of how much you invest in the content model and your editors, not in finding the cheapest platform. A team that treats the move as a simple tech swap based on license price will underperform one that is willing to pay more for proper workflow investment.
Why the best case studies involve leaving WordPress
I will be blunt about this. Go through the high-profile headless success stories of the last two years and the ones with the most substance are teams that have moved off WordPress entirely: Lyngen North on Sanity, Localcoin on Prismic, or a US e-learning outfit on Strapi. Strapi even has a detailed comparison of the case base on their blog. It is vendor-published, sure, but you see the same thing elsewhere.
It is hard to come by a publicly named “we went headless with WordPress” story that has the metrics to back it up. The architecture is out there but the wins are kept in-house. So if you are being swayed by a famous case study, check whether they are talking about WordPress or about a born-headless CMS like Sanity, Contentful or Strapi. Not to say keep-WordPress-headless is the wrong path, but be aware of the distinction.
Then again, the evidence is not as solid as vendor marketing would have you believe. You should let your own constraints drive the decision, not some pretty case study. For a more useful perspective, have a look at our headless CMS comparison for founders.When Headless WordPress Is The Right Call
A good fit tends to present itself in one of these ways:
- You have put in the work with WordPress over the years – custom editorial workflows, a team that puts out content every day and a body of work that would cost you to re-platform.
- The need to get that content to a second surface is genuine, not something you are just hypothesizing about.
- Whether in-house or via a partner, you have the engineering to put together a proper frontend application and content gateway, not merely a website.
- Leadership has the stomach for an initial dip in productivity and can see the 9 to 24 month ROI.
When To Stay Traditional
If it looks like this, you are probably better off sticking with what you have:
- Your output is one website. That “future mobile app” has been on the roadmap for two years but there is no signed scope for it.
- The team is used to page builders and plugin-driven workflows and you have no desire to put them through retraining.
- Performance or security is the issue, but you have not yet given a properly constructed traditional WordPress site its due.
- You are up against a tight timeline and budget and have to ship in a quarter.
Sometimes the most economical way to go headless is a custom theme on top of some serious hosting. It is not an exciting answer, but it is often the right one. We go into more detail on where each approach makes sense in our headless versus traditional CMS comparison.
What A Serious Headless Project Looks Like
Successful teams have certain habits in common. It has nothing to do with which framework you pick.
Front-load the content modeling. Don’t just carry over your old WordPress custom post types. Those were dictated by your plugins and themes, not your business. If you want the migration to be worth it, build a clean model from the ground up for multiple surfaces.
Make editor experience a product requirement. I am talking about custom Gutenberg blocks that correspond to actual frontend components, sandbox environments and proper training for the editors. And live preview before you launch, not tacked on afterwards. You will find that the projects which are abandoned are the ones where the editors had their say in month two.
Put a versioned layer between WordPress and the outside world. Use a small gateway service to normalize things and cache the hot paths so you have a stable contract with your consumers. In effect, WordPress is your internal database and the gateway is the CMS interface.
Be selective with your first use case. Pick one critical surface and some KPIs you can measure and give yourself six months to ship it. Do not try to re-platform everything at once.
Put a single product owner in charge of the content platform. You don’t want to be in a position where the WordPress and frontend teams are haggling over a Slack channel. Have one person with end-to-end accountability for both.
In Practice
We have been on both sides of this equation. Take when we put together Teton Gravity Research’s platform. The site was hard-pressed to stay up and they had 10,000 articles sitting in an old CMS. Headless was being considered, but before we got to framework talk, we had to determine what the site was supposed to do – the user-generated content features were more of a liability at that point – and put a content model in place that would hold up through the migration.
Then there is SingularityHub. For them, a decoupled rebuild was not the answer; a modernized WordPress build was. Theirs is a content-heavy site and the editors live in WordPress day in and day out. What mattered was a publishing experience they could trust, some better tooling and a cleaner UX. A headless layer would have just put a price tag on it without addressing any real business issue.
The common thread in these projects is that you let the needs of the editors, the readers and the business roadmap dictate the architecture. You don’t do it the other way around.
The Decision That Counts
Don’t think of headless WordPress as merely a CMS. It is a commitment to running your own content platform: the schema, the security, the preview system and the frontend app, all on top of the WordPress you already have. Some teams need to make that commitment, but for others it is an unnecessary expense.
Before you start talking frameworks, you have to decide if the performance or multi-channel advantages are worth the operating model they require. If they are, then by all means, treat the project as one of content-modeling and editor experience with WordPress as your database. If not, you will find a more conventional WordPress build to be the quicker and less costly way to get there.
If you are weighing that call before the budget is spent, our discovery process at Refact is designed to sort it out. We can help you come to a decision before you commit. In the meantime, you can see how we handle headless CMS development or get into the specifics of headless WordPress.
