WordPress as a Headless CMS with Next.js: Complete Setup Guide

What Is a Headless CMS Architecture?

In a headless setup, WordPress handles only content management (no PHP templates, no theme rendering). The content is delivered via the WordPress REST API or GraphQL (via WPGraphQL plugin). A Next.js frontend fetches that content and renders it as a fast, SEO-optimized static or server-rendered site. Editors get the familiar WordPress admin. Developers get the full power of React and Next.js.

Setting Up WordPress for Headless Use

Install WordPress on a subdomain (e.g., cms.yourdomain.com) or a separate hosting service. Install these plugins: WPGraphQL (for GraphQL API), Advanced Custom Fields + WPGraphQL for ACF (for custom fields in GraphQL), and Yoast SEO + WPGraphQL for Yoast (to expose SEO metadata via GraphQL). Disable your WordPress theme's frontend — you only need the admin and API.

Fetching WordPress Content in Next.js

Use Apollo Client or the lightweight graphql-request library to query your WordPress GraphQL endpoint. Create a lib/wordpress.js file with queries for posts, pages, and custom post types. In Next.js App Router, use server components to fetch data directly — no client-side loading states needed. Use generateStaticParams to pre-render all blog posts at build time for maximum performance.

Handling Images and Media

WordPress stores images on its own server. In next.config.js, add your WordPress domain to the images.remotePatterns array so next/image can optimize WordPress-hosted images. Alternatively, configure WordPress to use Cloudinary (via the Cloudinary WordPress plugin) so all media is served from Cloudinary's CDN with automatic format optimization and resizing.

SEO With Headless WordPress + Next.js

Use the Yoast SEO plugin and its GraphQL extension to query SEO title, meta description, and Open Graph data for each post. In generateMetadata() in your Next.js page, return these values from the WordPress API. This gives you the power of Yoast's SEO analysis in the WordPress admin while serving metadata through Next.js's optimized metadata system.

Preview Mode and Revalidation

Set up Next.js Draft Mode (formerly Preview Mode) so editors can preview unpublished WordPress posts in the Next.js frontend before publishing. Configure ISR (Incremental Static Regeneration) with a revalidate interval, or use on-demand revalidation triggered by a WordPress publish webhook. This keeps your static pages fresh without a full rebuild every time content changes.