Headless WordPress with Astro

A React framework typically renders the page on the server and then hydrates the whole tree in the browser, so the page becomes a running application. Even a page that is ninety per cent text pays for downloading and executing the code for all of it.

Astro inverts that. Every component renders to HTML at build time, and only components given a client directive — client:load, client:idle or client:visible — ship JavaScript and hydrate, each one independently. A blog post with a newsletter form and an image carousel sends JavaScript for those two islands and nothing else. That is how Astro sites routinely pass Core Web Vitals without careful tuning.

It also lets you mix frameworks. An island can be React, Vue, Svelte or plain Astro, which is useful when a client already has a React component they want to keep.

The WordPress REST API works with no extra plugins. Posts live at /wp-json/wp/v2/posts, and adding _embed includes the featured image, author and terms in one response. It returns at most 100 items per request, so paginate using the X-WP-TotalPages response header rather than assuming one request is enough.

WPGraphQL, a free plugin, lets you ask for exactly the fields each template needs, including related data, in a single query. On sites with many custom fields or relationships it produces smaller responses and fewer requests than REST.

For a straightforward site with posts, pages and a few custom fields, I use REST: it is always there and easy to inspect in a browser. Once a site has complex Advanced Custom Fields data or deep relationships between content types, WPGraphQL earns its plugin slot.

Astro's content layer lets you define a collection with a loader — an async function that fetches entries from anywhere and returns them with an id. Point a loader at WordPress, and posts become a collection you query with getCollection and getEntry, exactly like local Markdown.

Give the collection a schema with Zod. WordPress responses are loosely shaped: titles arrive as objects with a rendered property, featured images may be missing, and custom fields depend on plugin settings. Declaring the shape once means a missing field fails the build with a clear message instead of rendering undefined on a live page.

Map the response into a cleaner shape in the loader — title, slug, date, excerpt, html, image, categories — so templates never need to know what WordPress's raw JSON looks like.

• Render post content with the set:html directive. The HTML comes from your own WordPress editors, so treat the WordPress admin as a trusted boundary and restrict who can post unfiltered HTML.
• Load WordPress's block library styles or your own equivalents. Without them, Gutenberg columns, buttons and galleries render unstyled.
• Rewrite internal links in post content from the WordPress domain to the front-end domain, so links between posts stay on the Astro site.
• Add the WordPress media domain to Astro's allowed image domains if you want Astro's image component to optimise remote images.

A static Astro site only changes when it is rebuilt, so the editor's experience depends on rebuilds happening automatically. Netlify, Vercel and Cloudflare Pages all provide deploy hooks: a secret URL that starts a new build when it receives a POST.

On the WordPress side, a small plugin hooks transition_post_status and calls the deploy hook with wp_remote_post when a post is published, updated or unpublished. Debounce it — schedule a single event a minute or two out and skip scheduling if one is pending — so an editor saving ten times in five minutes triggers one build, not ten.

Build times grow with content. A few hundred posts build in well under a minute, but sites with thousands of pages should consider rendering low-traffic archive pages on demand rather than at build time.

• Previews. Editors expect the Preview button to show a draft. With a static site there is no draft page to show, so you need one server-rendered preview route, using an adapter and an application password to fetch the draft from WordPress.
• Search. There is no database query to run at visit time. Pagefind, which indexes the built HTML and searches it in the browser, works very well for content sites. WordPress's REST search endpoint called from an island is the alternative.
• Forms. Contact forms need somewhere to post: a form service, a serverless function or a REST endpoint on the WordPress side.
• Gated and personalised content. Memberships, logged-in dashboards and anything per-user need server rendering for those routes, and the more of the site that becomes, the less Astro's static model helps.

Astro is my default for headless WordPress when the site is mostly content: marketing pages, blogs, documentation, portfolios. Next.js is the better choice when the front end behaves like an application — user accounts, carts and checkout, dashboards, heavy client-side state — or when the team already works in React every day and wants one framework everywhere.

Before going headless at all, ask whether the site needs it. A well-built traditional WordPress theme is cheaper to run and simpler to edit. Headless with Astro is worth it when performance, security isolation or a multi-channel content model justifies running two systems instead of one.