Headless WordPress with Next.js: A Practical Guide

Introduction

I recently posted that headless WordPress + Next.js can be the pragmatic move if the content team already lives in WordPress. After a week of theory, I wired it up and learned a lot about what works and what doesn’t.

Why Headless WordPress with Next.js Works

If your editors are comfortable in the WordPress admin, the idea of pulling that content into a modern React framework feels natural. WordPress gives you a proven CMS, while Next.js offers fast, SEO-friendly rendering. The combination can be powerful, but it also brings hidden costs.

Setting Up the Stack

1. Separate domain , I spun up a new subdomain for the API layer. Keeping the frontend and backend isolated keeps deployments clean.
2. Install WordPress , A fresh install with the default theme. No custom theme needed because the frontend is Next.js.
3. Plugins , WPGraphQL to expose the data, Advanced Custom Fields (ACF) for custom fields, and the free-plan version of the WPGraphQL-ACF plugin.
4. Expose every field , With WPGraphQL you can query any field, but the free plan limits you to a single field type for repeatable content. I had to use a WYSIWYG field where a repeater would normally live.
5. Custom tables , For complex data I created custom tables and exposed them via GraphQL. This added another layer of maintenance.

Challenges and Workarounds

The biggest pain points were:
- GraphQL schema complexity , Every new field required a schema update. The free plan’s limits forced me to rethink how I stored repeatable blocks.
- Hosting and plan limits , The free plan on the hosting provider capped bandwidth and database size. Scaling required a paid plan.
- ACF overhead , While ACF is great for editors, it adds a runtime cost to each GraphQL query.
- Revalidation , I had to set up incremental static regeneration (ISR) in Next.js to keep content fresh. This required a webhook from WordPress to trigger revalidation.

Despite these hurdles, the workflow was still smoother than building a custom CMS from scratch. The editors could use familiar tools, and I could keep the frontend lean.

When to Choose Sanity

For a new project where I control the entire stack, I’d start with a content-model-first CMS like Sanity. The benefits are:
- Model fields first , Editors define the schema in code, and the API is generated automatically.
- No extra plugins , Everything is built into the platform; no need for WPGraphQL or ACF.
- Preview and revalidation , Sanity’s real-time preview hooks make ISR trivial.
- Cost-effective , The free tier is generous for small teams.

If the team already thinks in WordPress admin, the upfront tax of GraphQL and plugin maintenance may be worth it. But if you’re picking a CMS for a Next.js app from scratch, a content-model-first solution saves time and money.

My Takeaway

Headless WordPress with Next.js is not a silver bullet. It’s a pragmatic choice when you already have a WordPress-centric workflow. The glue, GraphQL schema, ACF, hosting limits, can become expensive and complex. For new projects, start with a CMS that models content first, like Sanity, and reserve WordPress for pure WordPress sites.

Final Thoughts

If you’ve tried WPGraphQL + ACF and still prefer it, or if you’ve switched to a different CMS, share your experience. I’m always curious about how teams balance editor experience with developer efficiency.

---
If you need a fullstack solution or want to discuss a project, reach out. Check out my portfolio at wabby.dev.