“Headless WordPress” is one of those terms that gets pitched confidently by developers before most clients have context to evaluate whether it’s relevant to their project. Sometimes it’s the right architecture. Often it’s engineering complexity added to a problem that didn’t need it.
Here’s a clear-eyed explanation of what headless WordPress actually is, what problem it solves, and the specific situations where it makes sense — versus the situations where a well-built traditional WordPress site is the better answer.
What Headless WordPress Means
Traditional WordPress has two parts: the backend (the admin interface, content storage, and PHP processing) and the frontend (the theme that renders that content into HTML pages for browsers). They’re coupled — the same WordPress installation that stores your content also handles how it’s displayed.
Headless WordPress separates these. The WordPress backend handles content management only. Its REST API or GraphQL endpoint (via WPGraphQL plugin) delivers that content as raw data (JSON) to a completely separate frontend application.
That frontend is typically built with a modern JavaScript framework:
- Next.js (React-based, supports server-side rendering)
- Gatsby (React-based, generates static HTML at build time)
- Nuxt.js (Vue-based, similar capabilities to Next.js)
The frontend makes API requests to WordPress, receives content data, and renders it using its own component system and styling. WordPress never directly serves HTML to the browser — it only serves data.
What Problem Headless Architecture Solves
Headless became popular for a specific set of use cases where traditional WordPress has real limitations:
Multi-channel content delivery. If the same content needs to appear on a website, a mobile app, a kiosk display, and a third-party platform, a headless CMS makes sense. One WordPress backend serves all channels via API. A traditional WordPress theme only knows how to render a website.
Performance at scale. A statically generated frontend (Gatsby, Next.js in static export mode) serves pre-built HTML files from a CDN. There’s no PHP processing, no database query, no WordPress theme rendering on each request. For sites with millions of page views, this architecture scales better and costs less per request.
Frontend technology flexibility. Some development teams are stronger in React or Vue than in PHP and WordPress template development. Headless lets them build the frontend in the tools they know best while still using WordPress as the content management interface clients are familiar with.
Complex application requirements. If your “website” is actually a web application — with client-side interactivity, real-time data, complex state management — a JavaScript framework frontend handles this better than PHP-rendered WordPress templates.
What Headless Doesn’t Solve (And Sometimes Makes Worse)
This is where most headless pitches go wrong.
Headless doesn’t inherently make sites faster. A well-built traditional WordPress site — hand-coded, no page builders, proper caching — scores 90+ on Lighthouse and delivers pages in under 2 seconds. Headless adds architectural complexity that can improve performance at scale, but doesn’t guarantee better performance for a typical business site. Many headless setups have slower initial page loads than a properly built traditional WordPress site.
Headless breaks many WordPress plugin integrations. WordPress plugins expect to work with WordPress’s template system. WooCommerce checkout, contact form plugins, SEO plugins like Yoast, and most third-party integrations assume traditional WordPress rendering. In a headless setup, these integrations either require significant custom development work or don’t work at all.
Headless significantly increases development cost. You’re now maintaining two codebases: the WordPress backend and the frontend framework. Deployments are more complex. Testing requires both systems. Developer expertise requirements are higher. For a standard business website, this overhead doesn’t pay off.
Headless makes content preview harder. WordPress’s built-in preview functionality — clicking “Preview” to see a draft before publishing — requires additional configuration in headless setups and doesn’t always work reliably without custom development.
The Actual Performance Comparison
Here’s the honest performance comparison between headless WordPress and a well-built traditional WordPress site:
| Metric | Traditional (well-built) | Headless (well-built) | Headless (average) |
|---|---|---|---|
| Lighthouse Mobile | 90–97 | 92–98 | 65–85 |
| TTFB | 150–300ms | 20–80ms (CDN) | 200–500ms |
| LCP | 1.0–2.0s | 0.8–1.5s | 1.5–3.5s |
| Dev complexity | Low-Medium | High | High |
The difference between a well-built traditional site and a well-built headless site is meaningful but not dramatic for most business sites. The gap between either and a poorly-built headless implementation is significant. Headless raises the floor of developer expertise required — a mediocre traditional WordPress build produces a mediocre site, but a mediocre headless build can produce an actively worse site.
Costs: What Headless Actually Adds
A custom traditional WordPress site costs $10,000–$20,000 for a professional build. Adding a headless frontend typically increases that by 40–80%:
- $15,000–$36,000 for a headless WordPress project of equivalent scope
- Ongoing hosting for two systems (WordPress on managed hosting, frontend on Vercel/Netlify)
- More complex deployment pipeline
- Larger ongoing maintenance surface area
That premium makes sense when headless architecture provides specific capabilities your project needs. It doesn’t make sense for a marketing website where a well-built traditional WordPress site delivers 95% of the performance benefit at 60% of the cost.
Who Actually Needs Headless WordPress
Be specific. Headless WordPress is the right answer when:
You have multiple content channels. Your WordPress content needs to power a website, a React Native mobile app, a progressive web app, and a third-party platform simultaneously. One backend, multiple frontends — this is what headless was built for.
You’re building at serious scale. Your site gets 5+ million page views per month and server-side PHP rendering at scale is creating infrastructure and cost problems. Static generation at CDN edge solves this. Smaller sites don’t have this problem.
Your frontend team is React/Vue specialists. The team that needs to build and maintain the frontend is stronger in JavaScript frameworks than in PHP/WordPress. Headless lets them work in their expertise without forcing a PHP learning curve.
You need advanced interactivity. Your “site” is actually a complex web application with real-time data, complex client-side state, and interactive features that go well beyond what WordPress themes handle.
You’re building a content platform with complex editorial workflows. A media company with dozens of content types, complex review workflows, and multiple editorial teams benefits from WordPress’s admin capabilities plus a custom-built editorial frontend.
Who Probably Doesn’t Need Headless WordPress
The majority of businesses asking about headless:
Small to mid-size marketing websites. 8–20 pages, a blog, a contact form, a few service pages. A well-built traditional WordPress site delivers 90+ Lighthouse scores, loads in under 2 seconds, and is easier to maintain. Headless adds cost and complexity for minimal gain.
WooCommerce stores. WooCommerce headless setups are a significant engineering undertaking. The checkout flow, cart management, account pages, and real-time stock updates that WooCommerce handles out of the box require substantial custom development to replicate headlessly. This is done — but rarely at small business economics.
Sites where content editors need reliable preview. If your marketing team publishes frequently and relies on WordPress’s preview functionality, headless creates friction that editors will notice.
Any project where budget is a primary constraint. If the question is “we have $15,000, should we go headless?” — almost certainly not. That budget is better spent on a fully custom traditional WordPress build with excellent performance than on a mid-range headless build with higher infrastructure complexity.
The Third Option: Decoupled WordPress
There’s a middle ground worth knowing about: decoupled WordPress. This uses WordPress as the CMS with traditional theme rendering for most pages, but adds React components for specific interactive features that benefit from client-side rendering.
A product comparison tool, a dynamic calculator, a real-time inventory display — these can be built as React components embedded in a traditional WordPress page, giving you the benefits of modern JavaScript for specific features without the full headless architecture overhead.
This approach is underutilized and often more appropriate than fully headless for mid-complexity business sites.
FAQ
Does headless WordPress work with WooCommerce? Yes, but it requires significant custom development. The standard WooCommerce checkout, account, and cart management pages are PHP-rendered WordPress pages. Making these work in a headless setup requires rebuilding those flows in your frontend framework against the WooCommerce REST API. This is doable and done — but it’s not plug-and-play.
Is headless WordPress faster than traditional WordPress? A well-built headless site can be faster, particularly for Time to First Byte when content is served from CDN edge nodes without server-side rendering. But a well-built traditional WordPress site with proper caching and no page builders scores 90+ on Lighthouse. The performance gap between the architectures, when both are well-built, is smaller than most headless pitches imply.
What is the WPGraphQL plugin and do I need it? WPGraphQL exposes your WordPress content through a GraphQL API endpoint. It’s an alternative to WordPress’s built-in REST API. Frameworks like Gatsby and Next.js can query WordPress content through either. WPGraphQL allows more efficient queries (request only the fields you need) and is preferred in most modern headless WordPress setups.
Can I use page builders with headless WordPress? The page builder controls the backend content storage and the content editor experience, not the frontend rendering. Elementor or Divi data can be queried through the API, but rendering it correctly on the headless frontend requires significant custom work. In practice, headless WordPress sites use custom field groups (ACF) rather than page builders for content structure.
What hosting does headless WordPress require? Two parts: your WordPress backend needs standard managed WordPress hosting (Kinsta, WP Engine, Cloudways). Your frontend needs deployment on a platform that supports your framework — Vercel (optimized for Next.js), Netlify, or similar JAMstack platforms. Typical cost is $30–$80/month for both, depending on scale.
Is headless WordPress harder to maintain? Yes. Two separate codebases, more complex deployment pipelines, more surface area for things to break, and a higher skill floor required for maintenance. The maintenance overhead is part of the cost calculation that’s often not surfaced in headless pitches.
Most businesses asking about headless WordPress are actually asking “how do I get a faster, more capable site?” The answer is usually a well-built traditional WordPress site — not a more complex architecture that adds cost and maintenance overhead. Our custom WordPress development consistently delivers 90+ Lighthouse scores without headless complexity. If you’re genuinely at the scale or use case where headless makes sense, get started with a conversation about what that project actually requires.