Headless WordPress keeps the editor your content team already knows and swaps the theme layer for a modern front end that you control. Done well, it buys you faster pages, a smaller attack surface, and the freedom to ship the same content to web, apps, and kiosks. Done badly, it doubles your infrastructure and breaks preview for every editor in the building. This guide covers how we approach it at Seahawk VIP after years of building headless stacks for enterprise teams.
The architecture in one picture
A headless build has three tiers, and each one needs an owner:
- The content tier. WordPress, usually on managed hosting, serving an API instead of HTML. Editors, media, roles, revisions, and plugins all live here.
- The rendering tier. A framework such as Astro or Next.js that fetches content at build time, request time, or both, and turns it into pages.
- The delivery tier. A CDN with cache rules that decide how long a rendered page lives at the edge and what invalidates it.
Most pain in headless projects comes from not deciding up front which tier is responsible for what. Write it down before anyone opens a terminal.
WPGraphQL or the REST API?
WordPress ships the REST API; WPGraphQL is a plugin. Both work in production at scale. Pick based on how your front end will consume content.
| REST API | WPGraphQL | |
|---|---|---|
| Ships with core | Yes | No (plugin) |
| Fetch exactly the fields you need | No, you get the full object | Yes, per query |
| Nested data in one round trip (post + author + terms + ACF) | Multiple requests or _embed |
One query |
| Caching at the edge | Simple: GET URLs cache well | Needs persisted queries or GET-based queries to cache cleanly |
| Tooling | Mature, boring, everywhere | Excellent schema explorer, typed clients |
| Custom fields | Register each field manually | ACF and most field plugins expose automatically |
Our default for new builds is WPGraphQL with persisted queries, because the rendering tier ends up making far fewer requests and the schema doubles as documentation. We reach for REST when a client already has REST integrations or a strict no-extra-plugins policy.
Whichever you choose, lock the API down: require authentication for anything beyond published content, disable user enumeration, and rate-limit at the CDN.
Preview is the feature that makes or breaks adoption
Editors do not care about your rendering pipeline. They care that clicking Preview shows them the page as it will appear. In a headless setup that button points at a WordPress theme that no longer exists, so you must rebuild it.
The pattern that works:
- WordPress’s preview link is filtered to point at a preview route on the front end, carrying the post ID and a short-lived token.
- The front end validates the token, fetches the draft or revision with an authenticated API call, and renders it with the same components as production.
- The preview route is explicitly excluded from the CDN cache and from search indexing.
Build this in the first sprint, not the last. If editors lose trust in preview, they will start publishing to check their work, and your cache invalidation becomes the next emergency.
Caching: three layers, three jobs
Headless sites are fast because almost every request never reaches WordPress. That only holds if the caching layers are set correctly.
- API response cache. Cache GET queries at the CDN or with an object cache. Invalidate on save with a webhook or the WPGraphQL Smart Cache plugin.
- Rendered page cache. For static output, the page is a file. For server-rendered output, cache at the edge with
stale-while-revalidateso a cold origin never blocks a reader. - Build or revalidation trigger. On publish, WordPress calls a webhook that either kicks a full build (static), revalidates specific paths (incremental), or purges cache tags (edge). Tag pages by post ID and taxonomy so a single update does not purge the whole site.
Measure cache hit ratio from day one. Anything under 90 percent on a content site means something is busting cache that should not be, usually query strings or personalization cookies.
Editorial workflow changes less than you think
The WordPress admin is unchanged. Roles, revisions, scheduled posts, and media still behave normally. What changes:
- Blocks need a front-end counterpart. Every core or custom block you allow must have a renderer. Restrict the block palette per post type so editors cannot insert a block that renders as nothing.
- Publish is no longer instant. Set expectations: a static build may take a few minutes; an incremental revalidation is seconds. Show build status inside the admin so editors are not refreshing the live site.
- Menus, redirects, and global settings need API exposure. Decide whether the front end or WordPress owns redirects; splitting that responsibility is a common source of 404 incidents.
- Plugins that render on the front end (forms, galleries, SEO output) will not work as-is. Audit the plugin list and replace front-end rendering with API-driven components.
When not to go headless
Headless is a serious investment. We advise against it when:
- The site is mostly marketing pages maintained by a small team, and a well-cached monolithic WordPress site already hits performance targets.
- You rely on a large plugin ecosystem for front-end features and do not have the engineering budget to replace them.
- There is no in-house or partner front-end team to own the rendering tier for the life of the site.
- Compliance requires a single vendor-supported stack, and your host does not support the split.
A monolith with full-page caching, image optimization, and a CDN will outperform a poorly maintained headless build every time. The decision should be about multi-channel delivery, front-end control, and team structure, not fashion.
Next step
If you are weighing headless for an enterprise WordPress property, Seahawk VIP can run a short architecture review covering API choice, preview, caching, and hosting fit before you commit engineering time. We build on WordPress VIP and other enterprise hosts and have shipped headless stacks on both Astro and Next.js, so you get a recommendation grounded in what we have actually operated.