Headless WordPress: keep the admin, replace the rendering
Headless WordPress is the pragmatic middle. It does not ask a newsroom to learn a new editor, does not ask the finance team to cancel a working subscription, and does not ask the client to migrate ten years of content. It asks one thing: stop letting WordPress render the page.
In short
- WordPress becomes a content API; Astro becomes the site.
- The admin stays familiar — same dashboard, roles, media library, revisions.
- Core REST API or WPGraphQL feeds the build; custom fields carry structure.
- The front‑end becomes static, fast and free of PHP at request time.
- You still run WordPress — patching, plugins and a PHP runtime remain your responsibility.
What headless WordPress actually is
A normal WordPress site does two jobs: store content and render it. Headless splits them. WordPress keeps the first job and exposes content over HTTP; the front‑end does the second.
Two ways to read the content:
- Core REST API —
/wp-json/wp/v2/posts,/pages,/media, plus custom endpoints you register. No plugins needed, works out of the box. - WPGraphQL — a schema‑driven alternative that fetches a whole page tree in one request, which matters on slow builds.
Structure comes from custom fields. Advanced Custom Fields (or its open‑source successor Secure Custom Fields) turns a page into typed data instead of a blob of block markup — and that is the single most important decision in a headless WordPress project. Without it, you are parsing HTML.
Who it fits
- Teams already on WordPress with an archive, a trained editorial staff and plugins they depend on.
- Publishers who need roles and workflows on day one, not after a migration.
- Clients who want a modern front‑end but cannot pause publishing for a quarter to change CMS.
- Projects with a fixed migration budget, where rewriting the editorial process is the expensive part.
It fits badly when the WordPress installation is already a liability — abandoned plugins, an unsupported PHP version, a theme nobody understands. In that case headless makes the front‑end fast while leaving the actual problem in place.
How it connects to Astro
Fetch at build time, prerender, deploy static:
// src/lib/wp.ts
const WP = import.meta.env.WP_URL
export async function getPosts() {
const res = await fetch(`${WP}/wp-json/wp/v2/posts?per_page=100&_embed`)
if (!res.ok) throw new Error(`WP: ${res.status}`)
const posts = await res.json()
return posts.map((p: any) => ({
slug: p.slug,
title: p.title.rendered,
date: p.date,
html: p.content.rendered,
}))
}
With WPGraphQL the same data arrives in one shaped query, which is nicer for pages built from flexible sections. Either way, the pattern is identical: fetch, map to your content model, render with your own components.
Publishing triggers a rebuild through a webhook — a small plugin or a function on the WordPress side calls your host’s deploy hook. For sections that change hourly, add on‑demand rendering for those routes and leave the rest prerendered.
Two setup details bite everyone exactly once. Authentication: the build only reads published content, so a read‑only application password is enough — write access stays inside the admin. Permalinks: the REST API lives under /wp-json, and permalink rules that swallow that path make the API answer 404s that look like authentication failures. Both are one‑line fixes — after you have spent an hour finding them.
Strengths
- Continuity. Editors keep the tool they know; nothing is retrained.
- Roles, revisions, media. Years of editorial features you do not have to rebuild.
- A real migration path. The front‑end is now your code, so leaving WordPress becomes a scheduled decision instead of a crisis.
- Performance and cost. Static pages on a CDN load fast and cost little to serve.
- Huge plugin ecosystem for everything around content — forms, CRM, translations.
Weaknesses
- PHP is still there. Updates, plugin hygiene and a supported runtime are mandatory; the 2026 PHP vulnerabilities (CVE‑2026‑109618 and CVE‑2026‑109619) are a reminder that the CMS host is a real attack surface.
- Block editor output is HTML, not structure — custom fields are not optional if you want clean components.
- Two systems to operate, with two deploy pipelines and two sets of credentials.
- SEO moves into your code. Meta tags, sitemaps and schema become front‑end work.
- Images need attention. WordPress generates its own sizes; Astro’s pipeline wants its own.
When to choose it
Choose headless WordPress when the cost of changing the editorial tool is higher than the cost of running two systems — which is true for most established publishers and for many clients with a decade of content. It is also the honest recommendation when a team is not ready for a schema‑as‑code CMS but the current site cannot stay as it is.
If the team is technical and wants the CMS in the repository, Payload is the cleaner long‑term home. If editors want visual previews, Storyblok delivers that out of the box.
Summary
Headless WordPress is a bridge, and bridges are useful when there is a river. You keep the admin, the roles and the archive, and you gain a fast static front‑end that you own — at the price of maintaining WordPress properly and moving SEO, images and previews into the front‑end.
See how it compares in the headless CMS comparison for Astro, or start from the headless CMS hub. We move sites from classic WordPress to an Astro front‑end without stopping publishing — that is web development work, and the reasoning behind it is in why we stopped starting new projects on WordPress.
Screenshots in this series are placeholders — we will replace them with our own, taken on real projects.
Yuri Osipov
Founder, SEO & analytics
Runs Take the Space. Specialises in technical SEO, measurable analytics setups and AI search visibility.