WordPress Headless CMS: The Developer's Guide [2026]

WordPress Headless CMS: The Developer's Guide [2026]

WordPress powers 43% of all websites according to W3Techs, and a growing number of teams are ripping out the PHP frontend entirely and using it as a content API. Here's everything you need to know about running WordPress headless, from choosing between REST API and WPGraphQL to deploying a Next.js frontend on Vercel with ISR.

What Is Headless WordPress? (And Why Should You Care?)

Headless WordPress is a setup where WordPress handles content management and storage while a separate frontend application, built with Next.js, Nuxt, Astro, or any framework, fetches that content through an API. WordPress keeps its admin dashboard, editor, plugin ecosystem, and MySQL database. But instead of rendering pages with PHP themes, it exposes content via the WordPress REST API or WPGraphQL, and your frontend takes over the presentation layer entirely.

Think of it this way: WordPress becomes the kitchen, and your frontend framework is the restaurant. The kitchen prepares the food (content), but the restaurant decides how to plate it, what the dining room looks like, and how guests experience the meal.

Traditional vs Headless Architecture

In traditional WordPress, everything is a monolith. A visitor requests a page, PHP processes the request, queries MySQL, runs it through your theme's template files, and sends back rendered HTML. The theme controls layout, styling, routing, everything.

In headless WordPress, you strip away that entire rendering layer. WordPress sits behind an API, usually on managed hosting like WP Engine or Kinsta. Your frontend, a React, Vue, or Svelte app, makes API requests to fetch content, then renders it however you want. The two systems can live on completely different servers, different tech stacks, different deployment pipelines.

There's a subtlety here that 9 out of 10 guides gloss over: decoupled and headless aren't exactly the same thing. Decoupled WordPress can still fall back to PHP rendering for certain pages (like the admin area or legacy routes). Fully headless means the WordPress frontend is completely disabled, it's API-only, no theme rendering at all. For this guide, we're talking about the fully headless approach.

When to Go Headless (and When to Stay Traditional)

Going headless makes sense when your team has frontend developers who want to work with modern tools, when you need to deliver content across multiple channels (web, mobile app, digital signage), or when performance is non-negotiable. It does not make sense for everyone, and being honest about that will save you weeks of wasted effort.

Go Headless When...

• Your team already knows React/Vue/Svelte. If your frontend devs are writing JSX all day, forcing them into PHP themes feels like asking a chef to cook with a microwave.
• You need multi-channel delivery. One WordPress backend can feed your marketing site, mobile app, and in-store kiosk through the same API.
• Performance is a hard requirement. Static pages served from a CDN edge will always beat PHP rendering on a shared server.
• You're running headless WooCommerce. Complex e-commerce frontends benefit enormously from custom React/Next.js storefronts.
• You want the modern DX. Hot module replacement, TypeScript, component libraries, CI/CD, the full frontend toolchain.

Stay Traditional When...

• Content editors need live preview and page builders. Gutenberg, Elementor, and WPBakery assume a traditional theme. Going headless kills most visual editing workflows.
• You're a solo developer or small team. Headless adds 40-60% setup complexity. If it's just you maintaining a blog, a traditional theme is simpler.
• You rely heavily on frontend plugins. Contact forms, SEO plugins (Yoast renders meta tags server-side), cookie consent banners, these all assume PHP rendering.
• Budget is tight. You'll need separate hosting for WordPress and your frontend. That's two bills instead of one.

REST API vs WPGraphQL: Choosing Your Data Layer

WordPress gives you two ways to fetch content in a headless setup: the built-in REST API and the WPGraphQL plugin. The REST API ships with WordPress core and works out of the box, no plugins needed. WPGraphQL requires installing a plugin but lets you query exactly the fields you need, eliminating the over-fetching problem that plagues REST. In our experience, WPGraphQL wins for most projects, but REST has one underrated advantage: native HTTP caching.

WordPress REST API: The Built-In Option

The REST API is available on every WordPress install since version 4.7 (December 2016). Hit /wp-json/wp/v2/posts and you get back JSON. Simple, well-documented, and it works with zero configuration.

The catch? Over-fetching. When you request a post, WordPress returns everything: rendered content, raw content, excerpt, author ID, featured media ID, categories, tags, meta fields, GUID, comment status, ping status, template, and about 15 other fields you probably don't need. For a blog listing page where you just need titles, slugs, and excerpts, you're transferring 3-5x more data than necessary.

// REST API: Fetch 5 recent posts with author and categories
const res = await fetch(
  'https://your-site.com/wp-json/wp/v2/posts?per_page=5&_embed'
);
const posts = await res.json();

// The _embed parameter includes author and category objects
// But also includes EVERY field on each post -- ~8KB per post
// For 5 posts, you're looking at ~40KB of JSON

You can use the _fields parameter to limit which fields come back (?_fields=id,title,slug,excerpt), but it doesn't help with embedded resources, and you'll still make multiple requests if you need related data.

WPGraphQL: Query What You Need

WPGraphQL is a free open-source plugin by Jason Bahl (now maintained by WP Engine) that adds a full GraphQL API to WordPress. You write a query specifying exactly which fields you want, and you get back exactly that, nothing more.

# WPGraphQL: Same query -- 5 recent posts with author and categories
query RecentPosts {
  posts(first: 5) {
    nodes {
      title
      slug
      excerpt
      date
      author {
        node {
          name
        }
      }
      categories {
        nodes {
          name
          slug
        }
      }
    }
  }
}

# Response: ~2KB of precisely structured JSON
# No extra fields, no bloat

Side-by-Side Code Comparison

Here's what the response payloads actually look like:

Which Should You Pick?

Use REST when you're building something quick, your team doesn't know GraphQL, or you need aggressive HTTP caching without extra tooling.

Use WPGraphQL when you're building a production frontend with complex data needs, you want smaller payloads, or your team already uses GraphQL elsewhere.

Bold verdict: For a serious headless WordPress project with Next.js, WPGraphQL is the better choice. The payload savings, developer experience with GraphiQL IDE, and single-request data fetching make it worth the plugin dependency.

Setting Up WordPress as a Headless CMS

Setting up WordPress as a headless CMS takes six steps: install WordPress, add the right plugins, configure your content model, disable the frontend theme, set up authentication, and verify your API is working. The whole process takes about 30-45 minutes if you've done it before, or a couple of hours the first time.

Step 1: Start with a fresh WordPress install on managed hosting. Kinsta, WP Engine, and Cloudways all offer environments optimized for WordPress. If you're just experimenting, a local install with LocalWP works fine too.

Step 2: Install the essential plugins:

Step 3: Create your content model with ACF. Define field groups that map to your frontend components. A portfolio post type might have fields for projectUrl, techStack (repeater), clientName, and projectYear.

Essential Plugins

WPGraphQL for ACF deserves special attention. Without it, your ACF fields won't appear in GraphQL queries. After installing, you can query custom fields like this:

query PortfolioProjects {
  projects(first: 10) {
    nodes {
      title
      slug
      projectFields {
        projectUrl
        clientName
        techStack
        projectYear
      }
    }
  }
}

Disabling the WordPress Frontend

Step 4: You don't want visitors hitting your WordPress URL and seeing a broken theme. Add this to your theme's functions.php or use a mu-plugin:

// Redirect all frontend requests to the API
add_action('template_redirect', function () {
    if (!is_admin() && !wp_doing_ajax() && !defined('REST_REQUEST') && !defined('GRAPHQL_REQUEST')) {
        wp_redirect('https://your-frontend-domain.com');
        exit;
    }
});

Step 5: Set up Application Passwords for authentication. Go to Users > Your Profile > Application Passwords, generate a password, and use it for authenticated API requests (creating/updating content from external tools).

Testing Your API

Step 6: Open your browser and hit https://your-site.com/graphql, you should see the GraphiQL IDE. Try querying your posts. If you're using REST, navigate to https://your-site.com/wp-json/wp/v2/posts and verify you get JSON back.

Pro tip: the GraphiQL IDE that ships with WPGraphQL is genuinely excellent for exploring your schema. You get autocomplete, documentation, and query history. It's the fastest way to figure out which fields are available and how your ACF data is structured.

Building a Next.js Frontend with WPGraphQL

The cleanest way to build a headless WordPress frontend in 2026 is with Next.js 15's App Router and React Server Components. Server Components fetch data on the server without shipping JavaScript to the client, and WPGraphQL gives you precise queries, it's a natural pairing. When I first set up WPGraphQL with Next.js App Router, the biggest gotcha was image handling, but we'll get to that.

Project Setup and Environment Variables

Start with a fresh Next.js project. Vercel also offers an official WordPress starter template if you want a reference architecture.

npx create-next-app@latest my-wp-frontend --typescript --app
cd my-wp-frontend

Create .env.local with your WordPress endpoints:

WORDPRESS_API_URL=https://your-wordpress-site.com
NEXT_PUBLIC_WORDPRESS_GRAPHQL_ENDPOINT=https://your-wordpress-site.com/graphql

Now create a lightweight GraphQL fetch utility. You don't need Apollo or urql for Server Components, plain fetch works perfectly because there's no client-side state to manage:

// lib/wordpress.ts
const API_URL = process.env.NEXT_PUBLIC_WORDPRESS_GRAPHQL_ENDPOINT!;

export async function fetchGraphQL<T>(
  query: string,
  variables?: Record<string, unknown>
): Promise<T> {
  const res = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables }),
    next: { revalidate: 3600 }, // ISR: revalidate every hour
  });

  const json = await res.json();
  if (json.errors) {
    throw new Error(json.errors[0].message);
  }
  return json.data;
}

For React framework options, check out our comparison of Next.js vs plain React with Vite, there are valid reasons to skip the framework, though for headless CMS work, the built-in SSR and ISR make Next.js the practical choice. And if you're debating between Next.js and Remix, we break that down in our post about why we recommend Next.js for most projects.

Fetching Posts with Server Components

Here's the blog listing page as a Server Component, no useEffect, no loading states, no client-side hydration:

// app/blog/page.tsx
import { fetchGraphQL } from '@/lib/wordpress';
import Link from 'next/link';

interface PostsData {
  posts: {
    nodes: Array<{
      title: string;
      slug: string;
      excerpt: string;
      date: string;
      author: { node: { name: string } };
    }>;
  };
}

const POSTS_QUERY = `
  query AllPosts {
    posts(first: 20, where: { status: PUBLISH }) {
      nodes {
        title
        slug
        excerpt
        date
        author {
          node {
            name
          }
        }
      }
    }
  }
`;

export default async function BlogPage() {
  const data = await fetchGraphQL<PostsData>(POSTS_QUERY);

  return (
    <main>
      <h1>Blog</h1>
      {data.posts.nodes.map((post) => (
        <article key={post.slug}>
          <Link href={`/blog/${post.slug}`}>
            <h2>{post.title}</h2>
          </Link>
          <p>{post.author.node.name} · {new Date(post.date).toLocaleDateString()}</p>
          <div dangerouslySetInnerHTML={{ __html: post.excerpt }} />
        </article>
      ))}
    </main>
  );
}

Dynamic Post Pages

Individual post pages use generateStaticParams to pre-render all posts at build time, then ISR picks up new content:

// app/blog/[slug]/page.tsx
import { fetchGraphQL } from '@/lib/wordpress';
import { notFound } from 'next/navigation';

const POST_QUERY = `
  query PostBySlug($slug: ID!) {
    post(id: $slug, idType: SLUG) {
      title
      content
      date
      author {
        node {
          name
          avatar {
            url
          }
        }
      }
      categories {
        nodes { name slug }
      }
    }
  }
`;

export async function generateStaticParams() {
  const data = await fetchGraphQL<{
    posts: { nodes: Array<{ slug: string }> };
  }>(`query { posts(first: 100) { nodes { slug } } }`);

  return data.posts.nodes.map((post) => ({ slug: post.slug }));
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const data = await fetchGraphQL<{ post: any }>(POST_QUERY, {
    slug,
  });

  if (!data.post) notFound();

  return (
    <article>
      <h1>{data.post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: data.post.content }} />
    </article>
  );
}

Don't forget to configure next.config.ts for WordPress images:

// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-wordpress-site.com',
        pathname: '/wp-content/uploads/**',
      },
    ],
  },
};

export default nextConfig;

Deploying Headless WordPress to Production

A production headless WordPress setup uses dual hosting: WordPress lives on managed WordPress hosting (WP Engine, Kinsta, or Cloudways), while the Next.js frontend deploys to an edge platform like Vercel or Netlify. This separation means each layer can scale independently, WordPress handles content editing and API requests, while the frontend serves static and ISR pages from CDN edge nodes worldwide.

Hosting Architecture

The data flow looks like this: content editors publish in WordPress admin, WordPress stores content in MySQL, the Next.js frontend fetches content via WPGraphQL, Vercel generates static HTML at the edge, and visitors hit the CDN, never touching WordPress directly.

For frontend hosting, check out our Vercel vs Netlify comparison for a detailed breakdown. Both work well for headless WordPress. If you're considering container-based alternatives, our Railway, Render, and Fly.io comparison covers those options too.

ISR and On-Demand Revalidation

This is the part that makes headless WordPress actually viable in production. We've found that on-demand revalidation is worth the setup effort because without it, you're stuck choosing between stale content (long revalidation intervals) and slow builds (short intervals that hammer your WordPress API).

ISR lets you set a revalidate time on each page. After that interval, the next visitor gets the cached page while Next.js regenerates it in the background. But the real magic is on-demand revalidation, triggering a rebuild the instant content is published:

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidation-secret');

  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid secret' }, { status: 401 });
  }

  const body = await request.json();
  const slug = body.post?.post_name;

  if (slug) {
    revalidatePath(`/blog/${slug}`);
    revalidatePath('/blog'); // Also revalidate the listing page
  }

  return NextResponse.json({ revalidated: true });
}

On the WordPress side, add a webhook that fires on publish_post using a plugin like WP Webhooks or a simple functions.php snippet that calls your Vercel /api/revalidate endpoint. Now content goes live within seconds of hitting "Publish", no full rebuilds, no waiting. See the Next.js ISR documentation for more configuration options.

Cost Breakdown

WordPress Headless vs Purpose-Built Headless CMS

After working with both WordPress headless and purpose-built CMSes like Sanity, Contentful, and Strapi, here's my honest take: WordPress headless is a pragmatic choice when you have an existing WordPress site or content team. It's rarely the best choice when starting from scratch.

Where WordPress Headless Wins

• Content editors already know it. WordPress's admin UI has 20 years of refinement. Training a non-technical team on Sanity Studio or Contentful's interface takes weeks.
• Plugin ecosystem. 60,000+ plugins. Need multilingual? WPML. E-commerce? WooCommerce. SEO content analysis? Yoast (still works in the admin). No purpose-built CMS matches this breadth.
• Hiring. WordPress has the largest developer talent pool of any CMS. Finding a WordPress developer is dramatically easier than finding a Sanity or Payload specialist.
• WooCommerce. If you need headless e-commerce with WordPress content, WooCommerce + WPGraphQL is a proven stack. Saleor and Medusa are alternatives, but WooCommerce has the market share.

Where Purpose-Built CMSes Win

• Content modeling. Sanity's GROQ, Contentful's content types, and Payload's TypeScript schema are designed for structured content from the ground up. WordPress's post/page/custom-post-type model feels bolted together.
• Real-time collaboration. Sanity has Google-Docs-style real-time editing. Contentful has live collaboration. WordPress? You get a "This post is being edited by someone else" lock screen.
• API-first architecture. WPGraphQL is brilliant, but it's still a plugin sitting on top of a PHP monolith. Contentful's API and Sanity's API were designed API-first from day one.
• Media handling. WordPress media library is functional but basic. Sanity's image pipeline with automatic crops, hotspots, and CDN delivery is a different class. Contentful and Storyblok integrate with Cloudinary natively.
• Developer experience. Strapi and Payload give you a local dev experience with hot-reload on schema changes. WordPress requires refreshing the admin and running database migrations.

Verdict: Which Should You Pick?

Use WordPress headless when: you have an existing WordPress site with years of content, your editors refuse to learn a new CMS, you need WooCommerce, or you need a specific WordPress plugin that has no equivalent elsewhere.

Choose a purpose-built headless CMS when: you're starting a new project from scratch, you need real-time collaboration, your content model is complex and structured, or your team values developer experience over plugin breadth.

At Techsy, we've built headless WordPress frontends for clients migrating from traditional WordPress. Our typical approach: WPGraphQL + Next.js App Router on Vercel, with ISR for performance and on-demand revalidation for content freshness. Get a free consultation ->

WordPress MCP and the Abilities API: The AI Future

WordPress 6.9 introduced the Abilities API, which is merging into WordPress 7.0 core (April 2026). It creates a standardized, typed, discoverable interface for WordPress functionality, think of it as WordPress exposing its capabilities in a machine-readable format that AI tools can understand and use.

The WordPress MCP Adapter bridges this Abilities API to the Model Context Protocol (MCP), the open standard for connecting AI systems to external tools. What does this actually mean? AI agents in Claude, Cursor, or VS Code can now discover what your WordPress site can do and then execute those actions directly.

Here's a practical scenario: Claude can create a WordPress post, populate ACF fields with structured data, assign categories, set a featured image, and trigger your Vercel revalidation webhook, all in one conversation. No browser, no admin panel, no copy-pasting.

This is early-stage, and the MCP adapter is still evolving. But it signals something important: WordPress isn't just sitting still while purpose-built headless CMSes innovate. The combination of Abilities API + MCP could make WordPress one of the most AI-accessible CMSes available, using its massive plugin ecosystem in ways that newer, smaller platforms can't match. Read the official announcement on the WordPress Developer Blog for the full technical details.

Performance: Headless WordPress vs Traditional WordPress

Headless WordPress with a static frontend dramatically improves performance compared to traditional PHP-rendered WordPress. Traditional WordPress serves dynamic pages by running PHP on every request, resulting in poor Time to First Byte (TTFB), according to performance data from mid-2025, only 31% of desktop WordPress clients and 24% on mobile see good TTFB scores. Going headless with Next.js and ISR means pages are pre-rendered and served from CDN edge nodes, dropping TTFB to under 100ms for cached pages.

WP Engine's case study on Android Authority showed a 6x improvement in Lighthouse performance scores after migrating to headless WordPress. Core Web Vitals data tells a similar story: only 45% of WordPress sites pass all three CWV metrics on mobile, compared to 65% for Shopify and 83% for Duda.

One important caveat: headless doesn't fix a slow WordPress backend. If your WordPress API takes 3 seconds to respond because you're on cheap shared hosting with 40 plugins, your ISR regeneration will be slow too. The frontend can't be faster than the API it depends on. Invest in quality managed hosting, it matters more in a headless setup, not less. WordPress Performance Lead Weston Ruter's blog has excellent data on what actually moves the needle for WordPress server performance.

FAQ

What is headless WordPress?

Headless WordPress is an architecture where WordPress serves as a content management backend only, with its PHP frontend theme completely disabled. Content is delivered through the REST API or WPGraphQL to a separate frontend application built with frameworks like Next.js, Nuxt, or Astro. The WordPress admin dashboard remains fully functional for content editors.

Is WordPress good as a headless CMS?

WordPress works well as a headless CMS when you have an existing WordPress site, content editors who know the interface, or need the plugin ecosystem (especially WooCommerce). It's less ideal than purpose-built headless CMSes like Sanity or Contentful when starting from scratch, because WordPress's content modeling and API were retrofitted rather than built API-first.

What are the disadvantages of headless WordPress?

The main disadvantages are: increased complexity (two hosting environments instead of one), loss of visual editing and page builder functionality, frontend plugins stop working (Yoast meta rendering, contact forms, cookie banners), no real-time content collaboration, and the GraphQL API is a plugin dependency rather than core functionality. Budget also increases since you're paying for WordPress hosting plus frontend hosting.

How do I connect Next.js to WordPress?

Install WPGraphQL on your WordPress site, then create a Next.js project with App Router. Set your WordPress GraphQL endpoint as an environment variable, write a simple fetch-based GraphQL utility function, and use it in Server Components to query posts, pages, and custom content types. No Apollo or urql needed, plain fetch works because Server Components run on the server.

WPGraphQL vs REST API, which is better?

WPGraphQL is better for production frontends because it returns only the fields you request (reducing payload size by 60-80%), supports nested queries in a single request, and provides a GraphiQL IDE for schema exploration. The REST API is better for quick prototypes, teams unfamiliar with GraphQL, or scenarios where native HTTP caching is critical without additional tooling.

How much does headless WordPress cost?

A minimal headless WordPress setup costs around $14/month, Cloudways for WordPress hosting plus Vercel's free Hobby tier for the frontend. A production setup with WP Engine and Vercel Pro runs $40-70/month. Add $0-50/month for premium plugins like ACF Pro and WPML. Purpose-built headless CMSes often have generous free tiers, so cost alone isn't a reason to choose WordPress headless.

Can I use WooCommerce with headless WordPress?

Yes. WPGraphQL has a WooCommerce extension (WPGraphQL WooCommerce or "WooGraphQL") that exposes products, orders, cart, and checkout functionality through GraphQL. This lets you build custom React storefronts with full e-commerce capability. The checkout flow requires extra work compared to traditional WooCommerce themes, but the performance and UX gains are significant for high-traffic stores.

Do I need a developer to set up headless WordPress?

Yes, a headless WordPress setup requires frontend development skills, specifically React (or Vue/Svelte) and familiarity with APIs. You'll need to build the entire frontend from scratch or customize a starter template. This is not a no-code solution. Content editors can still use the WordPress admin normally, but the initial setup and ongoing frontend maintenance require developer involvement.

What plugins are essential for headless WordPress?

The essential plugins are WPGraphQL (GraphQL API), Advanced Custom Fields or ACF (structured content modeling), and WPGraphQL for ACF (exposes custom fields via GraphQL). Strongly recommended: Custom Post Type UI for registering post types through the admin, and a webhook plugin like WP Webhooks for triggering frontend rebuilds on content publish. Avoid frontend-dependent plugins like Yoast SEO's meta rendering or form plugins.

Is headless WordPress good for SEO?

Headless WordPress can be excellent for SEO when implemented correctly with Next.js or Nuxt, because you get server-side rendering, faster page loads (improving Core Web Vitals), and full control over meta tags, structured data, and URL structure. The risk is that you lose automatic SEO plugin features like Yoast's meta tag rendering, you'll need to handle meta tags, sitemaps, and structured data in your frontend code manually.