Headless WordPress with Next.js: When It Makes Sense
Headless WordPress keeps WordPress as the place where editors manage content and uses a separate front end, such as Next.js, to display it through the REST API or GraphQL. It suits teams that need a custom front end and can maintain two systems. For most sites, normal WordPress is simpler.
This article is for developers and site owners deciding whether to split their WordPress site into a content back end and a separate front end.
What is headless WordPress?
In a normal setup, WordPress stores content and also renders the pages. In a headless setup, WordPress only stores and serves the content, and a different application renders the pages.
How the two sides talk
- REST API: Built into WordPress. It sends and receives JSON, and any language that can make HTTP requests can use it. Private, password-protected and custom content needs authentication or explicit configuration.
- WPGraphQL: A free, open-source plugin under GPL-3 that adds a GraphQL schema and API to a WordPress site.
What Next.js adds
With a static export, Next.js builds one HTML file per route and the result can be hosted on any server that serves static files. Server Components run during the build, so they can fetch your WordPress content and turn it into static pages.
What a static export cannot do
The Next.js documentation lists features that need a Node.js server or dynamic logic and are not supported in a static export. They include redirects and rewrites in the Next.js config, custom headers, Incremental Static Regeneration, Server Actions, draft mode and the default image optimization. For a headless site this has practical effects:
- Content changes appear only after you rebuild and redeploy.
- Editor previews need a separate preview setup.
- Redirects must be handled by your web server.
- Forms and search need an external service or your own API.
When it makes sense
| Good fit | Poor fit |
|---|---|
| A custom front end that themes cannot deliver | A brochure site or blog that a theme already covers |
| A team that can maintain two codebases | One person managing everything |
| Content reused across web, apps and other channels | Heavy use of plugins that output front-end features |
| Editors happy with WordPress as the content tool | Editors who rely on live visual page builders |
Decision checklist
- Name the problem a normal theme cannot solve.
- List the plugins you depend on and what each does on the front end.
- Decide how editors will preview content.
- Decide who maintains the front end and WordPress updates.
- Estimate hosting for both parts.
- Start with one section or page type before moving the whole site.
Common mistakes
- Going headless for speed alone, when caching and a lighter theme would do.
- Forgetting SEO basics such as canonicals, sitemaps and redirects in the new front end.
- Leaving the WordPress admin public and unpatched.
Frequently asked questions
Is headless WordPress faster?
It can be, because pages can be pre-built as static files, but speed depends on your implementation. A well-configured normal WordPress site can also be fast.
Do I need WPGraphQL?
No. The built-in REST API can feed a separate front end. WPGraphQL is an option if you prefer GraphQL.
Does Next.js static export support redirects?
No. Redirects are listed as unsupported in a static export, so your web server has to handle them.
Related
Sources
Need this built or fixed?
Start a proposal and our EU-sovereign team will scope it with you.
Start a proposal →