Over several years, we worked on migrating and running a large, high-traffic WordPress platform using a headless architecture. This wasn’t a proof of concept or a short-lived experiment — it was a real production system with millions of users, a busy editorial team, and strict performance and reliability expectations.
Headless WordPress helped us solve some hard problems. It also introduced new challenges that we didn’t fully anticipate at the start.
This post isn’t an argument for or against headless WordPress. It’s a reflection on what worked well, what didn’t, and what we would approach differently if we were making the same decisions again.
What we got right
Clear separation of concerns
Decoupling the frontend from WordPress gave us architectural freedom. Frontend teams could move faster, experiment with modern frameworks, and deploy independently without touching the CMS.
This separation also made responsibilities clearer: WordPress focused on content creation and management, while the frontend focused on presentation and user experience.
When the boundaries were respected, this worked well.
Frontend performance (when done deliberately)
Headless gave us the potential for excellent performance — but only when paired with strong caching strategies, disciplined API usage, and careful rendering decisions.
In cases where these were done well, we saw meaningful gains in perceived performance and flexibility. The key lesson here was that headless doesn’t guarantee speed; it enables it, if you earn it.
Long-term flexibility
The architecture allowed us to think beyond a single frontend. APIs could support multiple consumers, and the system was better positioned for future use cases without major rework.
That flexibility mattered at scale.
What we got wrong
This is where most of the learning happened.
We underestimated the editorial experience
Editors interact with the system every single day. Developers don’t.
In a traditional WordPress setup, content creation, previewing, and publishing are tightly integrated. In a headless setup, those guarantees disappear unless you rebuild them intentionally.
We struggled with:
- Reliable previews that matched the final frontend output
- Giving editors enough context to understand how content would appear
- Debugging “content issues” that were actually integration or caching problems
What looked like a clean architectural decision often translated into daily friction for editorial teams. In hindsight, we should have invested much earlier in tooling, previews, and workflows designed specifically for editors — not just developers.
Complexity didn’t disappear — it moved
Headless architectures are often sold as a way to simplify systems. In reality, the complexity just shifts location.
We introduced:
- Multiple caching layers
- More failure points
- Harder cache invalidation problems
- Less visibility into where things were breaking
Debugging production issues often meant tracing a request across several systems, teams, and deployment pipelines. Observability became critical — and we didn’t prioritise it early enough.
At scale, this kind of operational complexity becomes a real cost.
Team coordination cost was higher than expected
Splitting frontend and backend teams sounds clean on paper. In practice, it increases coordination overhead.
We saw:
- Frontend and backend teams moving at different speeds
- Knowledge silos forming naturally
- Onboarding new developers taking longer
- Simple changes requiring cross-team alignment
None of this was caused by people — it was a system design outcome. The architecture required stronger communication habits and clearer ownership than we initially planned for.
Assumptions we should have challenged earlier
Looking back, there were a few assumptions we accepted too easily:
- That headless would automatically improve performance
- That editorial challenges could be solved “later”
- That teams would naturally align across architectural boundaries
Each of these turned out to be only partially true. At scale, small assumptions compound quickly.
When headless WordPress actually makes sense
Despite the challenges, headless WordPress can be the right choice — under the right conditions.
From experience, it works best when:
- There are multiple consumers of the same content
- Teams are mature and comfortable owning long-term systems
- Editorial workflows are treated as first-class concerns
- There is budget and time for ongoing maintenance, not just initial build
Headless is not a shortcut. It’s a commitment.
What we would do differently next time
If we were starting again, we would:
- Invest in editorial experience from day one
- Treat caching and invalidation as product decisions, not infrastructure details
- Improve observability across the entire system early
- Write down architectural decisions and trade-offs explicitly
- Start with simpler decoupling patterns before going fully headless
Many of these lessons aren’t about technology — they’re about empathy, clarity, and long-term thinking.
Final thoughts
Headless WordPress isn’t a destination. It’s a trade-off.
At scale, the most important architectural decisions aren’t about frameworks or APIs. They’re about the people who build the system, the people who use it every day, and the teams who have to maintain it long after the initial excitement fades.
Sometimes the best systems are not the most flexible or modern — but the ones that remain understandable, reliable, and humane over time.