What is Headless WordPress?

Headless WordPress is an architecture in which WordPress is used only as a content management system (CMS) and content API, while the public frontend is built with a separate technology stack. The traditional WordPress theme layer (PHP, the WordPress template hierarchy, jQuery) is removed or ignored, and the frontend application fetches content from the WordPress REST API (available since WordPress 4.7 in December 2016) or from a GraphQL endpoint provided by the WPGraphQL plugin (over 60,000 active installations as of 2025). Popular frontend frameworks for Headless WordPress are Next.js (React based, from Vercel), Astro, Nuxt (Vue), SvelteKit, Gatsby (static site generator), Remix, Eleventy and Hugo. The frontend is deployed separately, often as static HTML on a CDN (Vercel, Netlify, Cloudflare Pages, AWS Amplify, Cloudflare R2) or as server side rendered Node.js on the edge. Adoption is driven by demand for faster page loads, better Core Web Vitals scores, modern developer experience and multi channel publishing to web, native apps and smart TVs from one content source.

How does Headless WordPress differ from classic WordPress?

In a classic WordPress install the same PHP process that stores content also renders the HTML. The visitor receives a page produced by a theme like Twenty Twenty Four, Astra, GeneratePress, Divi or Elementor. In a headless setup the PHP installation only serves as a JSON API. A typical request flow:

1. Visitor opens https://shop.example.com (the Next.js frontend on Vercel).
2. The frontend at build time or request time calls https://cms.example.com/wp-json/wp/v2/posts (the WordPress backend on a different domain).
3. WordPress returns JSON with title, content, featured image URL, author and so on.
4. The frontend renders the page as React or Vue components and ships HTML plus a small JavaScript bundle to the browser.

The WordPress admin remains untouched: editors still log in to cms.example.com/wp-admin, write posts in Gutenberg and manage media as usual. They just do not see their own theme on the public site.

Which APIs does Headless WordPress use?

What are the benefits of Headless WordPress?

• Performance: a static page deployed to a CDN at the edge is served in 20 to 80 milliseconds globally. Classic WordPress with a database query and PHP render typically takes 300 to 1500 ms TTFB without caching.
• Core Web Vitals: easier to hit LCP under 2.5 s, INP under 200 ms and CLS under 0.1 because the frontend ships only the JavaScript needed for hydration and can preload critical assets.
• Modern developer experience: React, Vue, Svelte, TypeScript, component libraries (Tailwind, shadcn/ui, Radix), hot module reload, deployment from Git, preview builds per pull request.
• Smaller attack surface: the public domain does not execute PHP. Common attack patterns like XML RPC brute force, plugin CVEs and SQL injection cannot hit the frontend. The WordPress admin can be locked down behind a VPN, basic auth or IP allowlist.
• Multi channel publishing: one WordPress backend feeds the website, a React Native mobile app, a Flutter app, a smart TV interface, a Slack bot and an Alexa skill from the same content.
• Scaling: traffic spikes on the public site do not touch the WordPress origin if the frontend uses Incremental Static Regeneration (ISR) or full static export.
• Editor unchanged: editors keep Gutenberg, custom fields, ACF, reusable blocks, scheduling and revisions.

What are the drawbacks of Headless WordPress?

• Higher cost: two systems to host, monitor and update. Two CI/CD pipelines. Two domains and TLS certificates.
• Preview broken: WYSIWYG preview in Gutenberg shows the unused theme, not the actual site. Workarounds include WPGraphQL Smart Cache + preview mode in Next.js or services like Faust.js by WP Engine.
• Plugins that inject HTML break: contact form plugins (Contact Form 7, WPForms), page builders (Elementor, Divi, Beaver Builder) and many SEO plugin features depend on rendering inside the WordPress theme. Yoast SEO has a WPGraphQL bridge, Rank Math too, but custom shortcodes from third party plugins need bespoke handling.
• SEO careful: canonical URLs, hreflang, sitemap, robots.txt, Open Graph and Twitter Cards must be mapped manually from the API into the frontend HTML.
• Build time: full static sites with thousands of posts need 5 to 30 minute builds. ISR (Next.js) and on demand regeneration help.
• Comments and forms: native WordPress comments do not render. Either disable them, switch to Disqus or build a custom comment UI that POSTs to the REST API.
• Cost of expertise: a React developer is more expensive than a PHP theme developer in most markets.

Which frameworks are most popular for Headless WordPress?

• Next.js (Vercel): the most common choice. Server side rendering, static generation, ISR, Edge Functions. Many starters (vercel/next.js example with WordPress, Faust.js from WP Engine).
• Astro: ships zero JavaScript by default, perfect for content sites. Astro 4.0 (December 2023) introduced View Transitions. Strong support for partial hydration (Astro Islands).
• Nuxt (Vue 3): comparable to Next.js but in the Vue ecosystem. Nuxt 3 since 2022 with Nitro server engine.
• SvelteKit: smallest bundle sizes, growing community.
• Gatsby: was the original SSG of choice for WordPress (gatsby-source-wordpress plugin). Acquired by Netlify in February 2023, slowing development.
• Eleventy (11ty): simple static site generator without a JavaScript framework.
• Remix: now bundled into React Router 7 (November 2024).

How do I host Headless WordPress?

• WordPress backend: any managed WordPress host works (Kinsta, WP Engine, Cloudways, Hetzner with a hand built stack, SiteGround). Some hosts have a dedicated headless plan: WP Engine Atlas, Kinsta Headless, Pantheon Decoupled, Strattic (acquired by Elementor in 2022).
• Frontend: Vercel (the home of Next.js, free tier for hobby), Netlify, Cloudflare Pages, AWS Amplify, Cloudflare Workers / Pages, Render, Railway, Fly.io. Static exports can also live on Amazon S3 + CloudFront, Cloudflare R2 or any plain web server.
• Content delivery: cache the API responses on the edge (Cloudflare Workers, Vercel Edge Cache) or use ISR so the WordPress origin is hit at most once per minute per page.

Concrete example with Next.js and WPGraphQL

// app/page.tsx in Next.js 15 App Router
async function getPosts() {
  const res = await fetch('https://cms.example.com/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `{ posts(first: 10) { nodes { id title slug excerpt date } } }`,
    }),
    next: { revalidate: 60 },
  });
  const json = await res.json();
  return json.data.posts.nodes;
}

export default async function Home() {
  const posts = await getPosts();
  return (
    <main>
      {posts.map(p => (
        <article key={p.id}>
          <h2>{p.title}</h2>
          <p>{p.excerpt}</p>
        </article>
      ))}
    </main>
  );
}

This page revalidates every 60 seconds, serves from the Vercel edge cache and only hits WordPress when the cache is stale.

When should I NOT go Headless?

• Small content site under 50 pages with no performance issues. Classic WordPress with a fast theme (GeneratePress, Astra, Kadence) and a caching plugin (WP Rocket, LiteSpeed Cache) plus Cloudflare is enough.
• You rely on page builders (Elementor, Divi, Beaver Builder) for visual editing and your team is not comfortable with React or Vue.
• You have hundreds of plugins that inject frontend HTML (booking calendars, ad inserters, membership flows).
• WooCommerce with complex checkout, although the official WooCommerce REST API and tools like Woocommerce Headless (WPGraphQL for WooCommerce) make it possible for product catalogs.

What about SEO in Headless WordPress?

Search engines render JavaScript but the safer path is server side rendering or static generation so the HTML already contains content on first response. Required mappings from WordPress to the frontend:

• Title tag, meta description, canonical URL, Open Graph, Twitter Card. Yoast SEO and Rank Math expose these via WPGraphQL.
• XML sitemap. Either proxy /sitemap_index.xml from WordPress through the frontend or generate it from the API.
• robots.txt.
• JSON-LD structured data.
• Redirects from old WordPress URLs to new frontend URLs (use Redirection plugin export + frontend rewrite rules).

How does InspectWP help with Headless WordPress?

InspectWP analyzes the public URL and detects whether it is served by a CDN like Vercel, Netlify or Cloudflare Pages instead of a classic WordPress origin by inspecting response headers (x-vercel-id, x-nf-request-id, cf-ray) and HTML signatures. WordPress detection runs against the API endpoint if a separate CMS subdomain is found.