Headless WordPress: What It Is, Pros and Cons, and How to Start

By Marko Denic
Contents
  1. How the front end gets the content
  2. The WordPress REST API
  3. WPGraphQL
  4. A static page with Astro
  5. Pros
  6. Cons
  7. Get SEO data from Yoast or Rank Math
  8. When does headless WordPress make sense?
  9. FAQ

Headless WordPress means using WordPress only as the back end: you write and manage content in the familiar admin, but the public website is a separate front-end app (built with Next.js, Astro, Nuxt or similar) that fetches the content through an API. The “head”, the theme that normally renders your pages, is cut off.

Traditional WordPress Headless WordPress
Who renders pages WordPress, with a PHP theme A separate JavaScript app
How content gets out Templates read the database directly REST API or GraphQL
Hosting One server WordPress + a front-end host
Plugins that change the front end Work out of the box Mostly don’t

How the front end gets the content

The WordPress REST API

Every WordPress site already has a JSON API at /wp-json/, no plugin needed. Posts, pages, categories, media and custom post types (with show_in_rest) are all available. Filter with query parameters, built safely with URLSearchParams.

javascript
const params = new URLSearchParams({
  per_page: 10,
  _fields: 'id,slug,title,excerpt,date', // only what you need
});

const res = await fetch(`https://example.com/wp-json/wp/v2/posts?${params}`);
const posts = await res.json();

posts.forEach((post) => console.log(post.title.rendered));

WPGraphQL

The free WPGraphQL plugin adds a GraphQL endpoint. You ask for exactly the fields you need, including related data, in one request. Most Next.js and Faust.js starters use it.

javascript
query LatestPosts {
  posts(first: 10) {
    nodes {
      slug
      title
      date
      featuredImage {
        node { sourceUrl altText }
      }
    }
  }
}

A static page with Astro

Astro fetches the posts at build time and outputs plain HTML, which is fast and fully indexable. Rebuild the site when content changes (a webhook on publish can trigger it).

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

const { post } = Astro.props;
---
<article>
  <h1 set:html={post.title.rendered} />
  <div set:html={post.content.rendered} />
</article>

Pros

  • Front-end freedom. Use React, Vue or Svelte, your own components and tooling, instead of PHP templates.
  • Performance. A statically generated or edge-rendered front end is very fast, and it doesn’t slow down when the admin is busy.
  • Security. The WordPress install can live on a private domain or behind authentication; the public site is just static files or a small app.
  • One content source, many channels. The same API can feed a website, a mobile app and other services.

Cons

  • You lose most of the plugin ecosystem on the front end. SEO plugins, form builders, page builders, comments and caching plugins expect to render the page themselves. You rebuild those features or find headless-aware alternatives.
  • Previews and editing get harder. “Preview” in the editor needs extra work to show drafts in your front end.
  • Two systems to build, host and maintain, and usually a higher cost.
  • SEO is your job. Titles, meta tags, sitemaps, redirects and structured data all have to be generated by the front end. And the front end must render HTML on the server or at build time, not only in the browser. Moving an existing site to the new front end? Map the old URLs with 301 redirects.

Get SEO data from Yoast or Rank Math

Both popular SEO plugins expose their output in the REST API, so your front end can reuse the titles, descriptions and schema you set in the editor instead of rebuilding them. Yoast adds a yoast_head_json field to every post.

javascript
const [post] = await fetch(
  'https://cms.example.com/wp-json/wp/v2/posts?slug=hello-world'
).then((r) => r.json());

const seo = post.yoast_head_json;
seo.title;          // "Hello World - My Site"
seo.description;    // meta description
seo.og_image?.[0];  // social image

When does headless WordPress make sense?

Good fit: a team with front-end developers, a site that needs app-like features, content shared across several platforms, or editors who love WordPress but developers who don’t want to write PHP themes.

Poor fit: blogs, small business sites and anything that depends on plugins for its features. For most of these, a fast classic theme is cheaper and simpler, and it’s why people choose WordPress in the first place.

The middle ground: keep a classic theme for server-rendered HTML, and add JavaScript components where you need interactivity, fetching from the REST API. This site works like that: pages are rendered by WordPress for speed and SEO, while a few Vue components load posts and power the tools through the API.

FAQ

Is headless WordPress free?

WordPress, the REST API and WPGraphQL are free. You pay for hosting two things, though: the WordPress back end and the front end (which can be free on Netlify, Vercel or Cloudflare Pages for small sites).

Is headless WordPress better for SEO?

Not by itself. It can be faster, which helps, but you have to rebuild everything an SEO plugin does. A well-built classic theme ranks just as well.

Can I use WooCommerce headless?

Yes, through the WooCommerce Store API, but checkout, payments and cart handling are significantly more work than with a theme.

Do I still need a WordPress theme?

Only a minimal one, so the admin and previews work. Some headless setups redirect all front-end WordPress URLs to the new site.