Headless WordPress with Next.js: How It Works, Pros & Cons

Why go headless at all?

Headless WordPress means keeping WordPress for what it does best, content editing, and handing the visitor-facing site to a modern JavaScript framework like Next.js. Your marketing team still logs into the familiar dashboard. Your visitors get a fast, app-like site that never touches a PHP theme.

It's not the right move for every site. A five-page brochure site for a local business is almost always better served by a well-built traditional WordPress theme. But for content-heavy brands, multi-channel publishing, or teams that want React-level control over the front end, headless can be a big upgrade.

This post covers how the architecture works, how a build actually comes together, and the honest pros and cons so you can decide whether it fits your project.

How the architecture works

A headless build splits one website into three layers that talk over an API.

  EDITOR
    │
    ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   WordPress     │────▶│   WPGraphQL      │────▶│    Next.js      │
│ cms.brand.com   │JSON │   or REST API    │     │  React + static │
│ posts, pages,   │     │                  │     │  HTML at build  │
│ menus, fields   │     └──────────────────┘     └────────┬────────┘
└────────┬────────┘                                       │
         │                                                ▼
         │           Publish webhook              ┌─────────────────┐
         └───────────────────────────────────────▶│    CDN edge     │
                 revalidate changed pages         │    VISITOR      │
                                                  └─────────────────┘

• WordPress becomes a content database with an editor on top. Its theme is never shown to visitors.
• The API layer (WPGraphQL or the built-in REST API) hands posts, pages, menus and custom fields to the front end as JSON.
• Next.js pulls that data, renders React components, and pre-builds pages as static HTML wherever it can. It also handles routing, SEO tags, images and draft previews.
• The CDN serves those pre-built pages from servers close to each visitor. When an editor hits Publish, a webhook tells Next.js to refresh only the pages that changed.

How it's done: building a headless WordPress + Next.js site

A production build comes down to eight steps. The WordPress side is mostly configuration; the real work lives in the Next.js app.

1. Expose your content through an API. WordPress ships with a REST API, but most headless builds use WPGraphQL, a free plugin that is becoming an official canonical WordPress plugin with Automattic's backing. GraphQL lets the front end ask for exactly the fields a page needs in one request.

   • Add WPGraphQL for ACF if you use Advanced Custom Fields.
   • Add the GraphQL extension for your SEO plugin (Yoast or Rank Math) so titles, descriptions and canonicals come through.

2. Model the content. Register custom post types and ACF field groups with show_in_graphql enabled. Structured fields (hero headline, CTA, testimonials) are far easier to render in React than one big blob of editor HTML.

3. Lock down the old front end. Put WordPress on a subdomain like cms.yourbrand.com, block it from search engines, and redirect any theme URLs to the new site so you don't create duplicate content.

4. Scaffold the Next.js app. Use the App Router and keep your GraphQL endpoint in an environment variable. A small fetch helper is all you need to start:

   // lib/wp.ts
   export async function wp<T>(query: string, variables = {}, tags = ['wp']) {
     const res = await fetch(process.env.WP_GRAPHQL_URL!, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ query, variables }),
       next: { tags }, // lets us invalidate this data on publish
     });
     const { data, errors } = await res.json();
     if (errors) throw new Error(errors[0].message);
     return data as T;
   }
   

5. Map WordPress URLs to routes. A catch-all route (app/[...slug]/page.tsx) looks up any URI with WPGraphQL's nodeByUri query and picks a template by content type, much like the WordPress template hierarchy. generateStaticParams pre-builds your most important pages.

6. Render the content. The quick route is injecting the post's HTML (sanitized). The better route parses Gutenberg blocks into data and maps each block to a React component, so editors keep the block editor and developers keep full control of markup.

7. Rebuild pages when editors publish. Pages are cached as static HTML. A save_post hook in WordPress pings a secured Next.js route handler, which marks just the affected data stale:

   // app/api/revalidate/route.ts
   import { revalidateTag } from 'next/cache';
   
   export async function POST(req: Request) {
     if (req.headers.get('x-secret') !== process.env.REVALIDATE_SECRET) {
       return new Response('Unauthorized', { status: 401 });
     }
     const { tag = 'wp' } = await req.json();
     revalidateTag(tag, 'max');
     return Response.json({ revalidated: true });
   }
   

   The 'max' profile marks the tagged data stale rather than deleting it: the next visitor is served the cached page immediately while the fresh copy is fetched behind them. If an editor needs the change to appear on the very next request instead, reach for updateTag in a Server Action.

8. Wire up previews and SEO. Use Next.js Draft Mode with an authenticated request so the WordPress Preview button shows unpublished drafts. Pull SEO fields into generateMetadata, and rebuild sitemaps and redirects on the Next.js side.

If you'd rather not assemble all of this by hand, Faust.js from WP Engine is a Next.js-based framework that packages previews, authentication and template routing for headless WordPress. Many teams still prefer plain Next.js + WPGraphQL for fewer opinions and fewer dependencies.

The pros

• Speed. Pages are pre-rendered and served from a CDN edge, so there's no PHP or database work on each visit. Strong Core Web Vitals become the default instead of a constant tuning project.
• Editors keep WordPress. No retraining and no migration to an unfamiliar CMS. Posts, pages, media, users and roles all work the way your team already knows.
• Security. The public site is static files and a few serverless functions. WordPress itself can sit behind a firewall or IP allowlist, which removes most of the attack surface that plugin vulnerabilities target.
• Total front-end control. No theme fighting, no page-builder markup bloat. Developers build with React components, TypeScript and modern tooling.
• Scales under traffic spikes. A launch or a viral post hits cached pages on the CDN, not your WordPress server.
• One content source, many channels. The same API can feed the website, a mobile app, a kiosk, an email system or an AI assistant.
• Easier redesigns. You can rebuild the front end later without touching the content, or swap the CMS later without rebuilding the front end.

The cons and hidden costs

• Many plugins stop working. Anything that outputs to the front end, such as page builders (Elementor, Breakdance), sliders, popups and most form plugins, does nothing on a headless site. Each one has to be rebuilt in React or replaced with a service.
• Higher build cost. You're building and maintaining two applications instead of one. Expect a larger upfront budget and a developer who knows both WordPress and React.
• Marketers lose visual page building. Editors can't drag a new landing page together the way they can in a builder. You can win most of that back with flexible block or ACF "section" components, but it takes planning.
• Previews take real work. The WordPress Preview button doesn't work out of the box. Draft previews need authentication and a dedicated route.
• SEO plumbing is on you. Titles, canonicals, schema, XML sitemaps and redirects that a plugin used to handle must be passed through the API and rendered by Next.js. Miss one and rankings can slip after launch.
• Two hosting bills, two things to monitor. WordPress still needs managed hosting and updates, plus a front-end host like Vercel or Netlify, and a deploy pipeline linking them.
• Content updates aren't always instant. Cached pages need revalidation hooks. If the webhook fails, editors see their change in WordPress but not on the live site.
• WooCommerce is hard. Headless carts, checkout and payment flows are a big project. Most stores are better served by a fast traditional build.

Should you go headless?

Go headless when performance, security or multi-channel publishing are worth a bigger build. Stay traditional when speed to launch, budget and marketer self-service matter more.

Your situation	Better fit
Content-heavy brand, publishes daily, traffic spikes	Headless
Same content feeds a website plus an app or other channels	Headless
In-house dev team comfortable with React	Headless
Strict security or compliance requirements	Headless
Small business site under ~20 pages	Traditional
Marketing team builds landing pages in Elementor or Breakdance	Traditional
WooCommerce store with lots of payment and shipping plugins	Traditional
Tight budget or launch deadline in weeks	Traditional

There's also a middle path: keep WordPress fully in charge of the site and move only one high-value section, such as a product configurator or resource library, to a React app.

Headless WordPress isn't an upgrade by default. It's a trade: more performance and control in exchange for more engineering. Get the API, previews, revalidation and SEO plumbing right on day one, and editors get a CMS they know while visitors get a site that feels instant.

How RAWR builds headless WordPress sites

We use a modern, AI-accelerated stack that keeps WordPress for content and puts every other layer on purpose-built tools. The result is a faster build without cutting corners on code quality.

1. WordPress for content. Your team writes and publishes in the dashboard they already know. We set up WPGraphQL, custom fields and SEO data so every piece of content is structured and ready for the front end.
2. Claude for design. If you don't have a design already, we use Claude to create the full website design: page layouts, components and a design system. You review and refine it before any code is written.
3. Claude Code for the build. We build the Next.js front end with Claude Code, pairing AI speed with 18+ years of hands-on web development. Every component, query and SEO detail is reviewed by a human before it ships.
4. GitHub for the codebase. All code lives in a GitHub repository with full version history, so changes are tracked, reviewable and reversible. You own the repo.
5. Vercel (or similar) for deployment. Every push to GitHub deploys automatically to a global CDN, with preview links for each change before it goes live. Netlify and other hosts work too if you have a preference.

This workflow lets us deliver headless builds in a fraction of the traditional timeline, while you keep full ownership of your content, design and code.

Thinking about going headless? RAWR builds both traditional and headless WordPress sites, so we'll tell you honestly which one fits. Get in touch for a quick architecture review.