Headless WordPress: How to Set Up a Decoupled Architecture with Next.js

Traditional WordPress handles both content management and frontend rendering in a single monolith. In a headless architecture, WordPress serves only as a backend CMS while a modern framework like Next.js takes over the frontend. The result: faster page loads, better developer experience, and unlimited frontend flexibility. This guide walks you through configuring WordPress as a headless CMS, fetching data with WPGraphQL, and building a production-ready Next.js frontend.

What Is Headless WordPress?

Headless WordPress disables the theme layer (frontend) and serves content exclusively through REST API or GraphQL. Content editors continue using the familiar WordPress admin panel, but the pages visitors see are rendered by a separate frontend application rather than WordPress itself.

Data Layer with WPGraphQL

WordPress ships with a built-in REST API, but GraphQL is more efficient for frontend development. The WPGraphQL plugin exposes your WordPress data through a GraphQL endpoint. A single query can fetch posts, authors, categories, and featured images together - something that requires 3-4 separate requests with REST API.

query GetPosts {
  posts(first: 10, where: { status: PUBLISH }) {
    nodes {
      id
      title
      slug
      excerpt
      date
      featuredImage {
        node {
          sourceUrl
          altText
        }
      }
      author {
        node {
          name
          avatar { url }
        }
      }
      categories {
        nodes { name slug }
      }
    }
  }
}

Installing and Configuring WPGraphQL

Install WPGraphQL from the WordPress admin panel via Plugins > Add New. Alternatively, use Composer:

# Install WPGraphQL via Composer
composer require wp-graphql/wp-graphql

# Test the GraphQL endpoint
curl -X POST https://cms.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ generalSettings { title } }"}'

After installation, the https://yoursite.com/graphql endpoint becomes active. Enable the GraphiQL IDE from WordPress admin under GraphQL > Settings to test queries in the browser. For security, disable introspection in production environments.

Setting Up the Next.js Frontend

Next.js is the most popular frontend framework for headless WordPress. With SSG (Static Site Generation), ISR (Incremental Static Regeneration), and SSR (Server-Side Rendering) support, it delivers a powerful combination of performance and SEO. Let's create the project and connect it to WordPress.

# Create a Next.js project
npx create-next-app@latest headless-wp --typescript --app

# Install GraphQL client
npm install graphql-request graphql

Create a client module to connect to the WordPress GraphQL endpoint:

import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient(
  process.env.WORDPRESS_GRAPHQL_ENDPOINT!
);

export async function getAllPosts() {
  const query = gql`
    query AllPosts {
      posts(first: 20, where: { status: PUBLISH }) {
        nodes {
          slug
          title
          excerpt
          date
          featuredImage {
            node { sourceUrl altText }
          }
        }
      }
    }
  `;
  const data = await client.request(query);
  return data.posts.nodes;
}

export async function getPostBySlug(slug: string) {
  const query = gql`
    query PostBySlug($slug: ID!) {
      post(id: $slug, idType: SLUG) {
        title
        content
        date
        author { node { name } }
        categories { nodes { name slug } }
        seo { title metaDesc }
      }
    }
  `;
  const data = await client.request(query, { slug });
  return data.post;
}

Blog Listing and Detail Pages

Create the blog listing page using Next.js App Router. The generateStaticParams function fetches all post slugs at build time and generates static pages:

import { getAllPosts, getPostBySlug } from '@/lib/wordpress';

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export default async function BlogPost({ params }) {
  const post = await getPostBySlug(params.slug);

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

Performance Strategy with ISR and SSG

The biggest advantage of headless WordPress is the ability to generate pages as static HTML at build time. However, rebuilding for every content update is impractical for frequently updated sites. ISR (Incremental Static Regeneration) solves this: pages are served statically while being regenerated in the background at specified intervals.

Instant Updates with On-Demand Revalidation

When a post is updated in WordPress, you can send a webhook to Next.js to instantly regenerate the relevant page. This eliminates the ISR waiting period:

import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

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

  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { slug } = await request.json();
  revalidatePath(`/blog/${slug}`);
  revalidatePath('/blog');

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

Deployment and Server Architecture

A headless WordPress architecture involves two separate server components: the WordPress backend (CMS) and the Next.js frontend. You can host these on the same server or on separate servers. The separate server approach provides independent scaling and security isolation.

We recommend running the Next.js application with PM2 in production. Build and start commands:

module.exports = {
  apps: [{
    name: 'headless-wp',
    script: 'node_modules/.bin/next',
    args: 'start',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};

Server Sizing Guide

Server requirements for headless WordPress projects vary based on traffic volume and content size. The following table shows recommended configurations for different scales:

Hosted Cloud servers are ideal for headless architecture. NVMe SSD disks and instant resource scaling deliver high performance for both WordPress backend and Next.js frontend. For WordPress staging environment setup, check our WordPress Staging guide.

Frequently Asked Questions

Conclusion

Headless WordPress combines the power of content management with modern frontend technologies. WPGraphQL provides efficient data fetching, Next.js ISR delivers static performance, and on-demand revalidation enables instant updates. This architecture is a powerful solution for projects targeting high performance, requiring multi-platform support, and demanding custom UI designs.