Headless WordPress with Astro: The Ultimate Guide

Why Headless?

WordPress is the world’s most popular CMS, powering over 40% of the web. Its content editing experience is unmatched. However, its frontend architecture (themes, PHP templates) can sometimes feel clunky compared to modern JS frameworks.

Headless WordPress decouples the two:

• Backend: WordPress (Content API)
• Frontend: Astro (or React/Next.js)

Why Astro?

Astro is the perfect candidate for a headless frontend because of its Islands Architecture. It ships zero JavaScript by default, only hydrating interactive components when necessary. This results in incredibly fast load times and perfect SEO scores—exactly what content sites need.

The Architecture

1. WordPress: Exposes content via REST API or GraphQL (WPGraphQL).
2. Astro: Fetches data at build time (getStaticPaths) to generate static HTML pages.
3. Deployment: The static site is deployed to a CDN (Cloudflare Pages, Vercel).

Fetching Data

Using fetch to get data from WordPress is straightforward in Astro:

// src/pages/[slug].astro
export async function getStaticPaths() {
  const res = await fetch('https://api.mysite.com/wp-json/wp/v2/posts');
  const posts = await res.json();
  
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;

Handling Blocks

The trickiest part of headless WordPress is rendering the Gutenbery blocks. You receive HTML content from the API.

You can simply render it:

<article set:html={post.content.rendered} />

Or, for more control, parse the blocks using a library like @wordpress/block-serialization-default-parser and map them to Astro components.

Caching & Revalidation

Since Astro builds static pages, you need a way to trigger rebuilds when content changes in WordPress. Use specific webhooks (via plugins like WP Webhooks) to trigger a deployment on your hosting provider whenever a post is published or updated.

Conclusion

This stack gives you the best of both worlds: marketers get the WordPress interface they love, and developers get a modern, performant DX with Astro.