Headless WordPress means using WordPress purely as a content backend — editors publish through the familiar wp-admin interface, while a separate frontend, usually Next.js, fetches that content through an API and renders it. The theme layer gets replaced entirely; the CMS underneath it doesn’t change at all.
What Actually Changes, and What Doesn’t
In a standard WordPress site, PHP templates render HTML directly from the database on every request. In a headless setup, WordPress exposes its content through the REST API (built in since WordPress 4.7) or through WPGraphQL, a plugin that adds a structured GraphQL layer. Next.js fetches that content at build time, on a schedule, or on demand, renders it into React components, and serves the result from a CDN. When an editor publishes, a webhook triggers revalidation so the static pages refresh automatically.
Editors keep the exact WordPress admin they already know. Visitors never touch WordPress directly — every page they see is rendered and served by Next.js.
REST API or WPGraphQL: How to Actually Choose
The REST API is built in, well-documented, and enough for moderate content models — start there for a simple site. Switch to WPGraphQL specifically once the frontend starts making two or three REST requests to assemble what should be a single logical page, or once query complexity or payload size becomes a real cost. WPGraphQL lets the frontend request exactly the fields it needs in a single call, which eliminates the over-fetching that REST endpoints are prone to on content with several nested relationships.
The Architecture in Practice
- WordPress stores and manages content through its familiar interface — nothing about the editing experience changes.
- WPGraphQL or the REST API exposes that content as structured data instead of pre-rendered HTML.
- Next.js fetches the data, typically inside React Server Components, and renders it using whichever mix of static generation, ISR, or server rendering fits each page type.
- A hosting platform’s edge network serves the rendered pages globally, with webhook-triggered revalidation keeping content current without a full rebuild.
What Happens to WordPress’s Plugin Ecosystem
This is the part most headless WordPress guides gloss over: backend plugins survive the transition only if their data is exposed through the API. SEO plugins like Yoast and Rank Math normally render meta tags server-side through PHP — in a headless setup, that metadata has to be pulled through the API and mapped into Next.js’s own Metadata API instead, or it never reaches the page at all. ACF field data is generally accessible via the API with the right configuration. WooCommerce product and order data can be accessed headlessly, though the checkout flow itself typically needs custom handling. Frontend-dependent plugins — visual page builders, contact form plugins that render their own markup, cookie consent banners built for PHP rendering — are the ones that usually don’t survive the move and need a Next.js-native replacement.
When Headless Is the Right Call
- Performance and Core Web Vitals genuinely matter, and the site’s audience or SEO strategy depends on them.
- Content needs to power more than one frontend — a website, a mobile app, and a third channel all reading from the same WordPress backend.
- The team includes React/Next.js developers who can own the frontend, not just WordPress theme developers.
When It’s Not Worth It
- A solo developer or small team maintaining a blog. Headless adds an estimated 40–60% setup complexity over a traditional theme — real overhead for a site that doesn’t need the performance gain.
- Editors who rely on live visual editing. Gutenberg, Elementor, and similar page builders assume a traditional theme is rendering the preview. Going headless breaks most of that visual workflow, and editors lose the WYSIWYG experience they’re used to.
- Budget is genuinely tight. A headless build takes real developer time upfront that a traditional WordPress site doesn’t require.
Production Details Worth Getting Right Early
- Lock the content model before writing frontend code. Map every post type, field, and relationship in WordPress first — changing the content model mid-project is expensive because it forces changes on both sides of the API.
- Ship draft preview on day one. Editors need to preview unpublished content through Next.js’s built-in draft mode, not by guessing based on the old theme.
- Plan redirects and metadata migration before launch, the same as any platform migration — this is where SEO rankings are most commonly lost in a rushed headless rebuild.
- Use Application Passwords (built into WordPress since version 5.6) for authenticated requests — needed for previewing drafts or writing data back, not for reading public published content.
The Bottom Line
Headless WordPress isn’t a WordPress replacement — it’s a way to keep the editing experience WordPress users already know while handing the actual rendering to something faster. It’s real added complexity, and it isn’t the right call for every site, but for a content-heavy site where both editor experience and page speed genuinely matter, it’s the setup that gets both instead of trading one for the other. For the fuller picture of when to choose this over a plain WordPress site or a plain Next.js app, see our WordPress vs Next.js comparison.
Need a site built or fixed? See Next.js & WordPress web development services