This is part of an ongoing series I am writing as I work my way through the modern web stack from a WordPress developer’s perspective. It is for people who, like me, have built on the web for years and still hit words in a modern stack they could not confidently define. The goal is broad literacy, not deep mastery: by the end you should be able to read any modern stack list and know what each piece does.
Each post comes with an audio companion (10-15 minutes, generated via NotebookLM) for gym or commute listening. Press play below if that suits you better than reading.
Most WordPress veterans have heard “headless WordPress” pitched at them at least three times in the last five years. Once in 2019 (decoupled themes are the future, marketing said). Once in 2021 (now with Next.js and Faust.js, the messaging promised). Once in 2024 (this time it is mature, the agencies insisted). Each time the messaging promised that headless was the inevitable evolution of the platform. Each time, most WordPress developers shrugged and went back to building Genesis child themes.
The skepticism was earned. Headless adds complexity. It also adds genuine value for specific project shapes. Knowing which is which, and being able to talk about it without either dismissing the idea outright or accepting the marketing wholesale, is one of the more useful things a WordPress developer can carry into 2026.
This module is the honest version. What headless WordPress actually is, when it makes sense, when it does not, and how WordPress fits as a backend in the modern stack you have just spent the last fourteen modules learning.
“Headless” means using WordPress as a content management system but rendering the frontend with something other than WordPress’s PHP templates. The WordPress backend keeps doing what it does well — editorial workflows, role management, the block editor, custom fields, the plugin ecosystem. The frontend becomes a separate application (Next.js, Astro, Nuxt, or a static site generator) that fetches data from WordPress over an API.
There are three pieces.
The content source. A regular WordPress install. The admin runs at cms.example.com or example.com/wp-admin. Editors use the block editor as normal. Posts, pages, custom post types, custom fields all work.
The API. WordPress exposes its content via REST (/wp-json/wp/v2/posts) or GraphQL (via the WPGraphQL plugin). The API serves JSON that the frontend consumes.
The frontend. A separate application that fetches content from the WordPress API, renders pages with React/Vue/Astro/whatever, and serves them to visitors. The frontend might be hosted on Vercel, Cloudflare Pages, Netlify, or anywhere else. It runs independently of the WordPress install.
The trade-offs:
- Faster frontend (no PHP rendering on every request).
- Better developer experience (modern JS toolchain, type safety, component reuse).
- More moving parts (two codebases, two deploys, content invalidation patterns).
- Loss of the “WYSIWYG” preview in WordPress admin unless you wire up preview integrations.
The decision to go headless is essentially: “is the development and frontend benefit worth the operational complexity?” For an editorial team that updates content multiple times daily and a frontend that needs interactivity beyond what WP themes give, the answer is increasingly yes. For a small business site that updates twice a year, the answer is still no.
The WordPress Analogue
Mental model: Headless WordPress is to a traditional WordPress site what a chef using a separate kitchen and dining room is to one running both from the same counter.
The chef (WordPress) still cooks the content. The dining room (the modern frontend) is designed and operated separately. The food gets carried between them on a tray (the API). This is genuinely better for both rooms when the operation is large enough; it is overhead when the operation is small.
The other thing worth holding: WordPress as a CMS is still excellent. The block editor in 2026 is genuinely productive. ACF still does what ACF does. Editorial workflows, role management, scheduled publishing, multi-author bylines — WordPress has spent twenty years getting these right. Replacing them is much harder than replacing the frontend.
The headless patterns that work
The main patterns for headless WordPress in 2026:
WP REST API as data source. WordPress’s built-in REST API. Pure JSON. Works out of the box. Returns posts, pages, terms, media, custom post types. Most modern frontends can consume it directly. Sufficient for many headless setups.
WPGraphQL. A community plugin (now stewarded by WP Engine) that exposes WordPress data via GraphQL instead of REST. Useful when the frontend needs to fetch many related entities in one query. Larger learning curve, more setup, but better DX for complex applications.
Faust.js. A framework specifically for headless WordPress with Next.js, maintained by WP Engine. Handles authentication, preview, routing conventions. The most “batteries-included” headless option in 2026. Tightly coupled to WP Engine’s hosting but works independently.
WP-as-CMS for static sites. Use WordPress to author content, build a static site (Astro, Eleventy, Hugo) that fetches content at build time, serve the static HTML from any CDN. WordPress almost disappears from the public face of the site; it lives behind the admin URL only. This is the most performant pattern for content-heavy sites.
Decoupled “islands” architecture. Mostly-static frontend with small WordPress-powered widgets (a search box, a comments section, a member area) embedded via fetch calls. The frontend pretends to be a static site but pulls live content where needed.
| Approach | Best for | Frontend | Trade-off |
|---|---|---|---|
| WP REST + Next.js | Editorial sites with interactive frontend | Next.js, Astro, Nuxt | Most flexible, more wiring |
| WPGraphQL + Faust.js | Larger projects, complex content models | Next.js (Faust adds the conventions) | Strong DX, WP Engine ecosystem |
| WP + static site generator | Content sites that rarely update | Astro, Eleventy, Hugo | Best performance, slower content turnaround |
| Hybrid (decoupled islands) | Mostly-static with dynamic widgets | Any modern framework | Most complex, but very fast |
For 2026, the default decision tree: editorial team + complex frontend → WP REST + Next.js, with WPGraphQL only if the content model demands it. Content site without complex interactivity → WP + Astro. Small site that updates rarely → stay traditional WordPress, there is no headless dividend here.
What This Changes for WordPress People
Three practical implications.
The first is that you can keep the WordPress admin your clients love. Editorial teams know WordPress. They know how to add a post, schedule it, manage media, tag content. Replacing their tools is expensive and politically hard. Headless lets you upgrade the frontend without disrupting them.
The second is that the agency offering changes. You can pitch “we modernise your frontend with Next.js while keeping WordPress as your editorial backbone” — a story that lands better with skeptical clients than “we are rebuilding everything.” Hybrid stacks are easier to scope, easier to roll back, and lower-risk for everyone.
The third is that the WordPress economy reshapes itself around this pattern. WP Engine bought WPGraphQL and Faust.js to anchor a headless offering. Kinsta and Pantheon offer similar bundles. Smaller agencies specialising in “WordPress + Next.js” charge more than traditional WP shops because the skill set is rarer. For WordPress developers willing to bridge into modern frontend work, the rate card goes up.
The perpetually rough edges
A few traps.
Preview is the perpetually rough edge. WordPress’s “Preview” button assumes WordPress is rendering the page. In a headless setup, you need to wire the preview button to your separate frontend. Faust.js handles this for Next.js. Other setups require custom work. Make sure preview works on day one or your editorial team will revolt.
The cache invalidation problem is real. WordPress generates content; the frontend caches it. When an editor updates a post, the frontend needs to know to invalidate its cache. The patterns (webhooks, on-demand revalidation, time-based regeneration) all work but each one has trade-offs. Set this up explicitly, not by hope.
Plugin ecosystem becomes patchy. Many WordPress plugins assume they own the frontend. SEO plugins (Yoast, RankMath, The SEO Framework) need adaptation. Form plugins (Gravity Forms, WPForms) often require custom frontends. Analytics plugins do not work. Audit the plugins you depend on before committing to headless.
Two codebases, two deploys, two on-call rotations. Headless splits operational concerns. The WordPress install needs its own hosting, security updates, and monitoring. The frontend needs all of the above too. For a solo developer this is genuinely more work; budget for it.
WPGraphQL is community-maintained. Until 2024 it was a one-person project; WP Engine then bought it. The future is more stable now, but the schema can still shift between versions. Pin your dependencies.
Go deeper on headless
If you want to develop real intuition about headless WordPress, a few resources worth your time.
YouTube, gym or commute friendly:
- “Headless WordPress with Next.js” tutorials by WP Engine (various lengths). Sponsored content but technically correct.
- “WordPress as a Headless CMS” by Casey Bisson on the Pantheon channel (~30 min). Vendor-neutral perspective on the patterns.
Official docs worth bookmarking:
- WP REST API Handbook. The canonical reference. Read the “Authentication” and “Filtering” pages especially.
- WPGraphQL docs. Once you commit to GraphQL on WordPress, this is the daily reference.
- Faust.js docs. Even if you do not use Faust, the patterns are instructive for any headless WordPress setup.
Next post in the series is the keystone of the whole course: how the pieces wire up. Next.js + Supabase + Drizzle + Auth + Vercel + GitHub Actions, end to end. The bit nobody explains, which is why I am writing it last.
Related
Leave a Reply