How to Plan a Next.js Frontend for WordPress

Running WordPress behind a Next.js frontend is an excellent approach for teams that want to keep WordPress' editorial experience while building modern web applications with React. However, the challenge is making the right architectural decisions around APIs, caching, previews, rendering, deployment and hosting before the first line of application code is written.

This guide focuses on those decisions. You'll learn how experienced teams build production-ready Next.js WordPress architectures and how to avoid the implementation choices that become expensive to undo later.

Using Next.js with headless WordPress

Headless WordPress separates content management from frontend rendering. WordPress acts primarily as the CMS where editors manage pages, media and publishing workflows, while Next.js delivers the visitor-facing frontend. This separation:

• Replaces the traditional PHP theme layer with a React application: Instead of being limited to the WordPress rendering model, the frontend can use static generation (SSG), server-side rendering (SSR) or Incremental Static Regeneration (ISR) on a page-by-page basis. It also allows the same WordPress content to power websites, customer portals, mobile apps or any other frontend that can consume an API such as the WordPress REST API or WPGraphQL (more on that in the next section). For teams building beyond a conventional marketing site, that's the biggest reason to choose a custom Next.js frontend over a standard WordPress theme.
• Changes the operational model: Editors continue working in WordPress, while developers work almost entirely in the Next.js application. Deployments, caching, previews and frontend performance become responsibilities of the React application rather than the CMS itself. Decisions that were once hidden inside a WordPress theme become explicit architectural choices.
• May improve security: A headless setup doesn't make WordPress inherently more secure, but it does reduce the public attack surface because visitors interact with the Next.js application rather than the WordPress theme layer. Many production architectures go a step further by restricting direct access to WordPress so only editors and trusted API requests can reach it. Headless builds may also require fewer WordPress plugins, which can reduce potential attack vectors and the maintenance burden. However, WordPress still needs the same updates and security hardening, but much less of the application is publicly exposed.

When headless WordPress is the wrong choice

A headless WordPress architecture shouldn’t be the go-to choice for every project. A traditional WordPress website is usually the better choice if you:

• Have a small team without dedicated React or Next.js expertise.
• Need a marketing site, blog or brochure website with straightforward content and no complex frontend requirements.
• Rely heavily on plugins that assume WordPress controls page rendering, such as page builders, form builders, search plugins, membership plugins or other frontend-focused extensions.
• Prioritize rapid development and lower operational overhead over more frontend flexibility.

However, if you need multiple frontend experiences consuming the same content or rendering strategies beyond what a PHP theme can provide, a headless WordPress setup with Next.js becomes worthwhile.

Choosing between REST API and WPGraphQL

Once you've decided to decouple WordPress, the next architectural decision is the API your frontend will use to retrieve content:

• The WordPress REST API is built into WordPress and exposes content through resource-based endpoints such as /wp-json/wp/v2/posts. It's widely supported by plugins, requires no additional setup and is often the fastest way to get a headless project running. For smaller sites or applications with straightforward data requirements, that's often enough.
• WPGraphQL takes a different approach. Instead of requesting fixed endpoints, the frontend asks for exactly the fields it needs through a single GraphQL endpoint. That becomes increasingly valuable as content models grow more complex with custom post types, custom fields, taxonomies and deeply related content. Rather than making multiple requests or receiving large payloads that contain unused data, the frontend receives a response shaped specifically for the component rendering it.

Neither option is universally better. REST favors simplicity and broad compatibility. WPGraphQL favors flexibility, predictable data fetching and a developer experience that's often a better fit for larger React applications. The right choice depends less on traffic or website size than on the complexity of your content model and how your frontend consumes it.

Where content delivery network (CDN) caching changes the answer

When API responses are cacheable at the edge, the difference between one larger REST response and one smaller GraphQL response becomes less significant because repeat requests are served from the CDN instead of WordPress. At that point, cache hit rates and invalidation strategy have a bigger impact on performance than the API protocol itself.

That doesn't mean the APIs become interchangeable. GraphQL still reduces over-fetching and is generally easier to work with when components need highly structured data from multiple content types. REST remains an excellent choice when your frontend consumes predictable resources and can benefit from WordPress' built-in endpoints and broad plugin compatibility.

For most production headless WordPress projects, the question is which API produces data that's easiest to cache, invalidate and maintain as the application grows. Once a CDN sits between Next.js and WordPress, operational simplicity often becomes a more important optimization than raw response size.

How to fetch and cache WordPress content

Fetching content from WordPress is straightforward. The bigger architectural decision is when that content should be rendered and how long it should be cached.

Next.js gives you three rendering strategies:

• Static site generation (SSG) generates pages at build time and serves static files from the CDN. It's ideal for content that rarely changes, such as documentation or evergreen landing pages.
• Server-side rendering (SSR) renders pages on every request. Because content is fetched from WordPress in real time, it's the right choice for personalized experiences, authenticated pages or data that must always be current.
• Incremental static regeneration (ISR) sits between SSG and SSR. Pages are still served as static assets from the CDN, but they can be regenerated after deployment without rebuilding the entire application. For most headless WordPress websites, ISR becomes the default because it combines the performance of static pages with a publishing workflow that's practical for frequently updated content.

Caching works alongside these rendering strategies through Next.js' built-in Data Cache. Individual fetch() requests can be cached indefinitely, refreshed after a defined interval or retrieved on every request, allowing different parts of the same application to follow different cache policies.

The result is that rendering and caching become content decisions rather than site-wide settings. A homepage, product catalog, documentation page and search results page rarely have the same freshness requirements, so they shouldn't all follow the same strategy. 

By matching rendering and cache behavior to publishing frequency, you reduce load on WordPress while ensuring editors see changes reflected when they expect them.

Triggering on-demand revalidation

On-demand revalidation is the mechanism that keeps that cache aligned with the editorial workflow. Without it, ISR depends on a time interval. A page might regenerate every 60 seconds, 10 minutes or an hour, which is fine for low-stakes content but awkward when an editor expects a newly published page to appear immediately. 

On-demand revalidation replaces that waiting period with an event-based model. When a post, page or custom post type changes in WordPress:

1. WordPress sends a webhook to a secure endpoint in the Next.js application. 
2. That endpoint tells Next.js which route or cache tag to revalidate. 
3. The next visitor request gets a regenerated version of only the affected page, while the rest of the site stays cached.

For most production headless WordPress deployments, on-demand revalidation has largely replaced full-site rebuilds. It scales better, reduces unnecessary build times and ensures that content updates invalidate only the pages that actually changed instead of regenerating the entire frontend.

How to set up preview and draft mode

Preview is one of the first workflows that breaks when you decouple WordPress. In a traditional WordPress site, unpublished content is rendered directly by the theme. In a headless architecture, the frontend is a separate application, so it has no way of knowing that a draft exists unless you explicitly build that connection.

To set up post previews for draft articles in a headless WordPress Next.js site, you connect WordPress' Preview action to a secure preview route in your Next.js application. That route validates the request, enables Next.js Draft Mode and fetches the unpublished version of the post instead of the published one. Authenticated editors can then review draft content using the real frontend before publishing, while everyone else continues seeing the cached production site.

The result is a workflow that feels native to content teams while preserving the performance and caching benefits of a decoupled architecture.

Not to mention, you don’t have to start from scratch. Starter kits (covered below) can significantly reduce setup time while preserving the flexibility of a custom Next.js frontend. For teams that want complete control over the architecture, however, implementing the preview workflow directly with Next.js remains a perfectly valid option.

Rendering Gutenberg blocks as React components

Once WordPress stops rendering the frontend, Gutenberg blocks become structured data instead of HTML templates. Your Next.js application is now responsible for deciding how each block should appear on the page.

The workflow looks like this:

1. Fetch the page's Gutenberg block data from WordPress using the REST API or WPGraphQL.
2. Loop through the returned blocks in your Next.js application.
3. Match each block to a React component. For example, a Paragraph block renders a Paragraph component, an Image block renders an Image component and a Heading block renders a Heading component.
4. Render the page. As you add more Gutenberg or custom blocks, you simply create additional React components for them.

So, if you’re migrating from a traditional WordPress site to Next.js, anything that depended on the WordPress theme layer must either be rebuilt in React or replaced with an API-driven alternative. This includes navigation menus, search, forms, breadcrumbs and SEO output.

However, plugins that manage content, custom fields, SEO metadata, users, e-commerce or editorial workflows generally continue working because they extend WordPress itself.

Picking a Next.js WordPress starter

You don't have to start a headless WordPress project from an empty repository. Several mature starter kits handle the initial project structure, data fetching, routing and WordPress integration, allowing teams to focus on building features instead of wiring the stack together.

The right starter depends on how opinionated you want the foundation to be:

• gregrickaby/nextjs-wordpress is one of the strongest production-ready starters for WPGraphQL projects. It combines the Next.js App Router with WPGraphQL, Tailwind CSS, SEO support, image optimization and a clean project structure without locking you into an opinionated framework. Choose it when you want a production foundation but still want full architectural control.
• Faust.js is also a strong choice for WPGraphQL-first projects. It handles the hard WordPress-specific work, including previews, authentication, template routing and data fetching. Use it when editorial preview, draft content and WordPress-aware routing are core requirements, not nice-to-haves.
• Vercel's Next.js WordPress Starter is a solid REST API foundation for content sites. It is built for modern Next.js, React and TypeScript and works well when the project mainly needs posts, pages, categories, tags, featured images and standard WordPress content structures.
• Colby Fayock's Next.js WordPress Starter is useful when you want a more complete WordPress-theme-like baseline. Its goal is to recreate the kind of features teams expect from an out-of-the-box WordPress theme while keeping the frontend static and portable.
• next-wp-rest is a practical REST API boilerplate for teams that care about local development parity. It includes WordPress, MySQL, PHP, PHPMyAdmin and the Next.js client through Docker, making it easier to spin up the full stack consistently.

Regardless of which starter you choose, treat it as a long-term architectural decision rather than a quick bootstrap tool.

Where to host headless WordPress and Next.js

Most headless WordPress projects start with split hosting. WordPress runs on a managed WordPress host, while the Next.js frontend runs somewhere else. That setup works and for prototypes, it may be enough. But in production, it creates operational drag: two dashboards, two deployment models, two support paths and separate environment rules.

The better model is running both WordPress and Next.js under one operational roof, which is what Pantheon provides.

Pantheon is a WebOps platform for WordPress, Drupal and Next.js that gives teams one place to build, test, launch and manage modern web experiences. It also provides:

• Dev, Test, Live workflow: Teams can develop, validate and launch through structured environments instead of pushing CMS or frontend changes straight to production. Code moves up, while content can move down for realistic testing.
• Multidev for parallel work: Developers can spin up branch-based environments for features, bug fixes and experiments, making it easier to test WordPress schema changes, API behavior and Next.js components in isolation.
• Content Publisher: This connects Google Docs and Microsoft Word to Next.js sites, giving content teams a faster path from draft to preview to published page. For enterprise teams, that reduces dependency on developer tickets and keeps publishing workflows closer to where writers already work.
• Smooth scaling: Pantheon scales WordPress horizontally across containerized instances, helping sites handle traffic spikes without slowdowns or emergency infrastructure work.
• Global CDN: This helps serve cached pages and static assets closer to visitors, reducing origin load and improving performance for global audiences.

SPS Commerce shows why this matters in the real world. The company had a Next.js-powered SupplierWiki site on Netlify and its WordPress marketing site on Pantheon. The stack worked, but it created platform sprawl across a site with roughly 1,600 pages in five languages. By moving SupplierWiki to Pantheon, SPS Commerce consolidated WordPress and Next.js under one platform and gave writers and engineers the same structured workflow the company already trusted for WordPress.

Get started with Next.js on Pantheon

Building a headless WordPress site isn't the difficult part. Building one that's fast, scalable, easy to publish and straightforward to operate over the next five years is. The architectural decisions you make today determine how much complexity your team inherits tomorrow.

That's why the platform matters as much as the framework. With Pantheon, you can build, deploy and scale WordPress and Next.js together using the same enterprise-grade WebOps workflow trusted by some of the world's largest organizations. 

Launch your headless WordPress + Next.js website on Pantheon today!