Headless WordPress with Next.js: Architecture, APIs, and Deployment
Set up a Next.js front‑end that pulls data from WordPress via REST API or WPGraphQL, enable ACF Show in REST, and use ISR for near real‑time content updates.
Create a Next.js app that consumes WordPress REST API or WPGraphQL, enable ACF Show in REST API, and configure ISR for content pages, caching, webhooks, preview, and media handling.
Summary
Headless WordPress keeps WordPress as the content management system while Next.js becomes the user‑facing application that renders pages.
Editors continue to use the familiar WordPress dashboard to create posts, pages, media, and custom fields, but the public site is now generated by Next.js using routing, component rendering, and performance optimisations.
The connection between the two layers is an API: the WordPress REST API or WPGraphQL, with the latter offering more flexibility for complex content structures and nested relationships.
Incremental Static Regeneration (ISR) is recommended for content‑driven sites because it delivers static performance with near real‑time updates.
In addition to fetching content, a headless stack requires caching, webhooks to trigger rebuilds, preview functionality, efficient media handling, SEO metadata generation, external redirects, and frontend‑managed XML sitemaps.
ACF field groups can be exposed in the REST API by enabling “Show in REST API,” which places the fields under an acf object in the JSON response, eliminating custom register_rest_field() code.
The guide also covers deployment considerations, such as separate environments, preview workflows, and hosting choices.
Overall, the article provides a comprehensive roadmap for moving to a headless architecture while preserving editorial workflow and enhancing performance.
Key changes
- WordPress remains the CMS; Next.js handles routing, rendering, and UX.
- Data is fetched via WordPress REST API or WPGraphQL, with WPGraphQL preferred for complex relationships.
- Incremental Static Regeneration (ISR) offers static performance with near real‑time content updates.
- Headless stacks require caching, webhooks for rebuilds, preview, media handling, SEO metadata, redirects, and frontend XML sitemaps.
- ACF field groups can be exposed in the REST API by enabling “Show in REST API,” adding fields under an acf object in JSON.
- Deployment involves separate environments, preview workflows, and hosting choices.