Headless WordPress With Next.js: A Reference Architecture

A sound headless WordPress Next.js architecture has five layers: WordPress as the content source, an API layer (WPGraphQL or the WordPress REST API), a Next.js front end that chooses a rendering mode per route, a caching strategy that is purged when content changes, and a deployment setup that keeps the CMS private. Get those five decisions right and the rest is implementation detail. Get them wrong and editors, developers and visitors all feel it within weeks of launch.

This blueprint is for teams that have already decided to go headless. If that decision is still open, read when headless is overkill and hybrid WordPress makes more sense first, or the plain language overview in headless CMS explained for business owners.

The reference architecture for headless WordPress with Next.js

Think of the stack as a pipeline. Content is created in WordPress, exposed through an API, fetched and rendered by Next.js, cached at the edge and served to the visitor. Each stage has a clear owner and a clear contract with the next one.

Content modelling: design for the front end, not the page

In traditional WordPress, the theme decides how content looks, so loose content models are forgiven. In a headless build the front end receives raw data, so structure matters far more.

Structured fields over open ended layouts

Use custom post types for distinct content (services, case studies, team members, locations) and structured fields for anything the front end needs to place precisely, such as a hero heading, a call to action label or an Arabic summary. Keep the block editor for long form body content where editors need flexibility.

Blocks need a rendering contract

If editors use Gutenberg blocks, the Next.js front end must know how to render each one. Agree a limited block allowlist, map each block to a React component, and decide what happens when an unknown block appears (render nothing and log it, rather than breaking the page).

Languages and markets

For English and Arabic sites, decide early whether translations live as linked posts or as separate sites in a network, and how the front end resolves locale, direction (left to right or right to left) and hreflang. Retrofitting this later is expensive.

The data layer: WPGraphQL or the WordPress REST API

The WordPress REST API ships with core and sends and receives data as JSON. It exposes posts, pages, taxonomies and other built in types, and it applies the same authentication restrictions as the site itself. WPGraphQL is an open source plugin that adds a GraphQL schema and API to WordPress.

Many teams use both: WPGraphQL for reading content into Next.js, and the REST API for writes such as form submissions into custom endpoints. Keep data fetching in one module so the API can change later without touching every page.

Authentication for the API

Published content can usually be read anonymously. Anything unpublished, such as drafts and previews, needs authentication. WordPress has supported Application Passwords since version 5.6, sent with HTTP Basic Auth over HTTPS, and this is a common choice for server to server calls from Next.js. Store credentials as environment variables on the Next.js server only, never in client side code.

Rendering modes in Next.js: pick per route

The biggest advantage of Next.js is that each route can use a different rendering strategy. A good architecture maps content types to modes deliberately.

Static generation with Next.js ISR

Incremental Static Regeneration (ISR) serves prerendered pages and regenerates them in the background. According to the Next.js ISR documentation, a route can set a time based revalidate interval, after which the next request still receives the cached page while a fresh version is built. Pages can also be revalidated on demand with revalidatePath or revalidateTag. This suits blog posts, service pages and most marketing content.

Dynamic rendering

Search results, personalised dashboards and anything depending on cookies or query strings should render dynamically. Keep these routes few and fast, and cache the WordPress queries behind them where possible.

Mapping content types to modes

Note the documented caveats: ISR runs on the Node.js runtime and is not available in a static export, and when several instances run, on demand revalidation only reaches the instance that receives the call unless a shared cache handler is configured. That last point catches many self hosted builds.

Caching and invalidation, from origin to edge caching

Caching in a headless stack happens in several places at once. Treat them as one system with one invalidation plan.

1. WordPress object cache. A persistent object cache keeps API responses fast when Next.js regenerates pages. Our guide to WordPress caching layers explains the options.
2. Next.js data and page cache. Tag each fetch by content type and ID (for example, a post tag and a posts list tag) so a single webhook can purge exactly what changed.
3. Edge caching at the CDN. Static and ISR pages can be cached close to visitors. Make sure the CDN respects the cache headers Next.js sends, and that it is purged, or set with short lifetimes, when content changes.

The publish webhook

When an editor publishes or updates content in WordPress, a small plugin or hook should call a secured revalidation route in Next.js, passing the post type, slug and ID. That route calls revalidateTag or revalidatePath and, if needed, the CDN purge API. Log every call so "my change is not live" can be answered quickly.

Hypothetical example: a Dubai retailer updates a promotion banner used on 40 landing pages. If the banner is a shared block tagged once, one webhook refreshes every page that uses it. If each page fetched it without a tag, the team would have to wait for time based revalidation or purge pages one by one.

Preview mode and editor experience

Preview is where headless projects most often disappoint editors, so design it on day one. Next.js Draft Mode, described in the Next.js documentation, sets a cookie that makes the request bypass cached and prerendered content, while normal visitors continue to see the cached version. WordPress sends the editor to a secured preview route with a shared secret and the post identifier; Next.js validates both, enables Draft Mode and redirects to the page.

The detail matters: authenticated requests to WordPress for draft content, a visible "preview" banner, and an exit control. The full editorial side, including scheduling and approvals, is covered in editorial workflow in headless WordPress.

Security and authentication boundaries

One benefit of headless is that WordPress no longer needs to face the public. Use it.

• Keep the admin private. Put wp admin behind IP allowlisting, a VPN or an identity aware proxy where your hosting allows it.
• Expose only what the front end needs. Disable unused REST routes and GraphQL introspection in production, and limit query depth and complexity.
• Separate credentials by purpose. One read only account for builds and previews, another for any write operations, each with the minimum role.
• Protect the revalidation and preview routes. Both should reject requests without a valid secret and should never redirect to arbitrary URLs.
• Handle personal data deliberately. If forms collect personal data from UAE residents, decide where submissions are stored and processed, and confirm obligations under the UAE PDPL, or the DIFC or ADGM rules where they apply, with counsel.

Deployment and environments

Hosting the two halves

WordPress and Next.js have different needs. WordPress needs PHP, a database and a persistent file store for media (or offloaded media on object storage). Next.js needs a Node.js runtime for ISR and dynamic routes, plus a shared cache if it runs on more than one instance. Hosting them separately lets each scale on its own terms.

Environments that mirror each other

Run at least development, staging and production for both halves, with each Next.js environment pointed at its matching WordPress environment. Content usually flows down from production to staging by database copy; code flows up through version control and a build pipeline.

Release checklist

• Environment variables (API URL, secrets, preview token) set for each environment
• Webhook from WordPress pointing at the correct Next.js environment
• CDN cache rules tested for static, ISR and dynamic routes
• Redirects from any old URLs mapped in Next.js
• XML sitemap and robots rules generated by the front end, not WordPress

Plan your headless build with Codeeo

Codeeo designs and builds headless WordPress sites with Next.js front ends, from content modelling and API design to caching, preview and deployment. Our team of 80+ across Dubai, Riyadh and Karachi has delivered 200+ projects across the UAE and the US, and UAE clients can meet the team at our Dubai office. See our Next.js development and WordPress development services, or ask about Core Web Vitals work for an existing headless site.

If you already have an architecture in mind and want a second opinion, contact our team and share your content model, traffic profile and hosting constraints.