Headless WordPress is genuinely useful for some projects and an over-engineered tax for most others. The internet is full of breathless takes about why you “should go headless,” many written by the agencies who’d profit from selling you a Next.js front-end you don’t need. This handbook is the contrarian view: when headless WordPress is a great answer, when it isn’t, and how to make it work when you actually need it.
The core idea: headless WordPress means using WordPress as a CMS only — for content management — while a separate, decoupled front-end (typically Next.js, Astro, or Nuxt) renders the actual pages and pulls content via the WordPress REST API or WPGraphQL.
What you gain
Front-end performance. A Next.js site with static generation will outperform a typical WordPress theme on Core Web Vitals, often by 50–100ms on LCP. The compounding effect: better SEO, better conversion, better UX.
Developer experience. React, TypeScript, modern tooling, hot reload. PHP and the WordPress theme hierarchy feel slow and dated to JS-first developers. Real productivity gains, especially for complex front-ends.
One CMS, multiple front-ends. If you have a marketing site, a mobile app, and an email marketing tool all consuming the same content, headless lets you publish once and render everywhere.
Independent scaling. The Next.js front-end can scale on Vercel or Cloudflare independently of the WordPress backend. Hot articles don’t bring down the admin.
What you lose
The plugin ecosystem. Most WordPress plugins assume they’re rendering HTML. Forms, page builders, e-commerce, membership, anything that touches the front-end becomes either useless or significantly more work to integrate.
Live preview. WordPress’s preview feature breaks. You need to build custom preview that hits a separate Next.js preview environment with the draft content. Solvable, but more work than most teams expect.
Editorial UX. The WordPress editor still works, but the editor’s “what you see” no longer matches “what gets published.” Editors lose the visual feedback loop they had on classic WordPress. Most non-technical content teams find this jarring.
Two deployment surfaces. WordPress on one host. Next.js on Vercel or Cloudflare. Cache invalidation between them. Preview environments. Two sets of credentials, two domains, two monitoring stacks. Twice the operational overhead.
When headless makes sense
Five scenarios where the trade-off pays back:
1. You have multiple front-ends consuming the same content
A web app, a mobile app, an email newsletter, a partner widget — all reading the same articles, products, or events. Headless WordPress as a single source of truth pays for itself.
2. You’re already a JS-first team
If your engineers are React developers and you’re hiring more, fighting them onto PHP and theme hierarchy is a productivity tax. The headless decision is partly about who maintains the site for the next three years.
3. You have real performance requirements
Sub-1s LCP, sub-50ms TTFB, 95+ Lighthouse score. Possible on classic WordPress with serious work; significantly easier on a static-generated Next.js front-end.
4. The content model needs flexibility classic WordPress doesn’t offer
Complex localization, multi-tenant content, content composed from multiple sources at render time, deeply nested relationships between content types. The Gutenberg editor + ACF can do a lot, but eventually the limits show.
5. You want a hybrid where the marketing site is decoupled from the product
The marketing site is the front-end of a Next.js app that’s part of the same codebase as your product dashboard. WordPress provides the editorial surface for marketers; Next.js renders both the marketing pages and the product UI from one shared design system.
When headless is the wrong choice
Three scenarios where it’s almost always over-engineering:
1. A marketing site for a small business
If the site is 10–20 pages, updates twice a month, and is run by one or two people, classic WordPress with a custom theme is dramatically simpler. The decision framework lays out why.
2. You don’t have a JS-first engineering team
Headless requires ongoing maintenance of a Next.js codebase: dependency updates, framework upgrades, deployment monitoring, error tracking. If nobody on your team owns this, the headless setup will rot within a year.
3. You need a fast launch
A headless setup takes meaningfully longer to build than classic WordPress at the same scope. If “we need this live in three weeks” is a constraint, classic WordPress wins on speed alone.
The technical architecture (when you’re going for it)
The setup we’ve used on a dozen production headless WordPress sites:
WordPress backend
- WordPress 6.x on Kinsta or WP Engine, behind a custom domain like
cms.yoursite.com - WPGraphQL for the API (better DX than REST for nested queries)
- ACF Pro for custom fields, exposed via WPGraphQL for ACF
- Custom post types for any structured content (services, team, case studies)
- JWT or application passwords for authenticated reads (e.g., for preview)
Next.js front-end
- Next.js 14+ with App Router and React Server Components
- Static generation for marketing pages, ISR (Incremental Static Regeneration) for content that changes
- Apollo Client or urql for the GraphQL queries
- Tailwind CSS for styling
- Deployed on Vercel or Cloudflare Pages
The cache invalidation pipeline
This is the part most teams underestimate. When WordPress publishes new content, the Next.js front-end needs to know to revalidate. Options:
- Webhook + on-demand revalidation. WordPress fires a webhook to Next.js on save, which calls
revalidatePathorrevalidateTag. Cleanest pattern. - ISR with short revalidation windows. Pages re-fetch in the background every 60 seconds. Simpler but less precise.
- Time-based regeneration. Rebuild the whole site every X minutes via a cron job. Crude but bulletproof.
The cost premium
Honest numbers, based on the projects we’ve shipped:
- Classic WordPress site at 12 pages: $6,500–$12,000
- Headless WordPress + Next.js at 12 pages: $14,000–$25,000
- Annual maintenance differential: $2,000–$5,000 more for headless
That premium has to be paying for something concrete — performance, scaling, multi-channel delivery — to be worth it. If the answer is “we wanted to use Next.js,” that’s not enough.
The honest summary
Headless WordPress is a tool. Like all tools, it’s right for some jobs and wrong for most others. The agencies pushing it on every client are selling complexity for billable hours. The agencies refusing to use it on principle are missing real wins on the right projects.
Use it when the trade-offs pay back: multiple front-ends, JS-first team, performance-critical, content-model flexibility. Skip it when they don’t: small marketing sites, non-technical teams, fast launches, normal performance requirements. That’s the entire decision.
