Headless WordPress With Next.js: A Business Decision Guide

Headless WordPress with Next.js means keeping WordPress as the content management system while a separate Next.js application builds the pages visitors see. It is worth it when your front end needs to behave like an application, pull from several data sources or share content across channels, and when you have the development capacity to run two systems. For most content and lead-generation sites, a well-built traditional or block-theme WordPress site is cheaper and simpler.

This guide starts with the business decision, then explains the architecture choices that determine whether a headless build succeeds.

Decide first: is headless right for you?

The decision comes down to whether the benefits of a custom front end outweigh the cost of running and maintaining two systems. WordPress accounts for roughly 64% of CMS-driven mobile sites (Web Almanac 2025), and the vast majority of WordPress sites run a traditional theme, so headless remains a minority architecture. That is not a reason to avoid it, but it is a reason to have a clear purpose.

Signs headless is a good fit

• App-like front end. Dashboards, logged-in experiences, configurators or complex filtering that would be awkward in a theme.
• Multiple data sources. Pages that combine WordPress content with product data, inventory, a CRM or other APIs.
• Multiple channels. The same content feeds a website, a mobile app, kiosks or partner sites.
• An existing React or Next.js team that will own the front end long term.
• Strict front-end control over performance budgets and design systems that a theme makes difficult.

Signs it is not

• The site is mostly marketing pages and a blog.
• Editors rely on visual page building and instant previews.
• The site depends on plugins that output front-end features (forms, SEO, WooCommerce checkout, membership gating).
• There is no developer who will own the front end after launch.
• Budget is tight and the main goal is "faster," which a well-built WordPress theme can often deliver.

A quick scoring framework

Score each question 0 (no), 1 (partly) or 2 (yes):

1. Does the front end need app-like interactivity beyond standard pages?
2. Does content need to combine with data from other systems at render time?
3. Will content be published to more than one channel?
4. Do you have developers committed to maintaining a Next.js codebase?
5. Can you budget for two hosting environments and two codebases for several years?

A total of 7 or more suggests headless deserves a serious look. A total of 5 or 6 means you should run a short discovery or prototype before committing. A total of 4 or less usually means a traditional build is the better investment. This is a practitioner rule of thumb, not a formula, but it forces the right conversation. For a comparison focused on lead generation specifically, see headless website vs WordPress for lead generation.

How a headless WordPress architecture works

In a headless setup, WordPress stores content and exposes it through an API. Next.js requests that content, renders HTML (at build time, on request or on a schedule) and serves it to visitors, often from a CDN. Editors still log in to the familiar WordPress dashboard.

The key decisions are how Next.js gets content, how editors preview drafts, how published changes reach the live site, and how search engines see the pages.

REST API vs WPGraphQL

WordPress offers two practical ways to deliver content to Next.js.

The REST API is built into core and "provides an interface for applications to interact with your WordPress site," with endpoints for posts, pages, taxonomies and other data; private content requires authentication (WordPress REST API Handbook). WPGraphQL is "a free, open-source WordPress plugin that provides an extendable GraphQL schema and API for any WordPress site" (WPGraphQL docs), and it became a canonical plugin on WordPress.org in October 2024 (WordPress.org News).

Factor	REST API	WPGraphQL
Availability	Built into WordPress core	Free plugin, canonical on WordPress.org
Request style	One endpoint per resource type	One endpoint; the query defines the shape of the data
Related content	Often several requests, or custom endpoints	Posts, authors, terms and fields in one query
Payload size	Returns the default response unless fields are limited or customized	Returns only the fields requested
Learning curve	Familiar to most developers	Requires GraphQL knowledge
Extending with custom data	Register custom routes and fields	Register types and fields in the schema
Good fit	Simple content, integrations, write operations	Content-rich sites with related data and many templates

For authenticated requests, such as fetching drafts for preview, WordPress supports Application Passwords, built into core since WordPress 5.6. They use HTTP Basic Auth and are accepted only over HTTPS; the Basic Auth plugin is for development and testing only. Cookie authentication requires a wp_rest nonce sent as X-WP-Nonce (REST API authentication). Store the credentials as server-side environment variables in Next.js, never in browser code (do not use the NEXT_PUBLIC_ prefix for secrets).

Previews with Next.js Draft Mode

Preview is where many headless projects frustrate editors, so plan it from day one. Next.js Draft Mode lets an editor see draft content on the real front end by bypassing caches for that request, while other visitors keep getting cached pages (Next.js Draft Mode docs).

The typical flow:

1. The editor clicks Preview in WordPress, which opens a URL on the Next.js site containing a shared secret token and the post identifier. This works once WordPress's preview link is customized (for example with the preview_post_link filter) to point to the Next.js preview route.
2. A Next.js Route Handler checks the token against a secret stored in environment variables.
3. If it matches, the handler enables Draft Mode and fetches the draft from WordPress using authenticated credentials.
4. The handler redirects the editor to the page for that post.

One detail matters for security. The Next.js docs warn to redirect to the slug of the post you actually fetched, not to a path passed in the URL, to avoid open-redirect vulnerabilities (Next.js Draft Mode docs).

Publishing updates with ISR and webhooks

Incremental Static Regeneration (ISR) lets Next.js update static pages without rebuilding the whole site. With on-demand revalidation, you call revalidatePath or revalidateTag, for example from a CMS webhook, so the affected pages refresh when content changes (Next.js ISR docs). The current docs recommend calling revalidateTag(tag, 'max'), with a cache profile as the second argument.

A practical setup:

1. A small plugin or custom code hooked to post status changes sends a webhook to a Next.js route when a post is published, updated or deleted (WordPress core has no outgoing webhooks).
2. The route verifies a shared secret.
3. It revalidates the post's path, plus any listing pages, category pages or tags that include it.
4. The cached page is marked stale and regenerates on the next request; with stale-while-revalidate behavior, that first request may still get the old copy while the fresh version builds in the background.

Two caveats from the Next.js documentation are easy to miss. ISR is not supported with static export, so a purely static deployment cannot use it. And when the app runs on multiple instances, the default cache is per instance unless you add a shared cache handler, which can mean some visitors see stale content after a revalidation (Next.js ISR docs). Your hosting choice should account for both.

SEO on a headless site

Headless can be excellent for SEO or quietly harmful, depending on rendering. Google processes JavaScript sites in crawl, render and index phases, and says "server-side or pre-rendering is still a great idea because it makes your website faster for users and crawlers," noting that not all bots can run JavaScript (Google Search Central). Google also calls dynamic rendering "a workaround and not a recommended solution," recommending server-side rendering, static rendering or hydration instead (Google Search Central).

Next.js handles server and static rendering well. The gap is everything an SEO plugin did automatically in a theme. A headless build needs to provide:

• Title tags, meta descriptions and canonical URLs pulled from WordPress fields.
• Open Graph and social tags.
• XML sitemaps and a robots.txt that reflect front-end URLs.
• Structured data where relevant.
• Redirects managed somewhere editors can reach.
• Correct status codes for missing and moved pages.

If your SEO plugin exposes its data through the API, the front end can read it. Either way, a developer has to wire it up and test it.

When NOT to go headless

In our experience, headless is chosen more often than it is needed. Avoid it, or at least delay it, when:

• The site is a content or lead-generation site without app-like needs. A traditional or block-theme build is cheaper to build and maintain, and our advanced WordPress development guide shows how to get strong performance from one.
• You cannot fund two systems. Headless means two codebases and two hosting bills, every year.
• You rely on front-end plugin features. Forms, search, SEO output, membership gating, WooCommerce's cart and checkout and block-styled layouts all have to be rebuilt in Next.js.
• Editors need visual editing. Previews work, but the polished builder-style experience usually takes significant extra work. If your concern is page-builder weight, custom Gutenberg blocks may solve it without decoupling.
• You expect headless to remove WordPress security work. It can reduce what is publicly exposed if the WordPress origin is locked down (separate hostname, access restrictions), but the WordPress back end still needs updates, access control and hardening. Our WordPress security hardening checklist still applies.

Making the call

Headless WordPress with Next.js is a strong architecture for the right project: app-like front ends, multiple data sources and teams ready to run two systems. For everything else, the traditional stack is simpler and usually sufficient. If you are weighing the options, Robustech's WordPress development team can score your project against the framework above and recommend the lighter path when it fits.