Headless WordPress Without Regretting It Later

Headless WordPress sounds like the best of both worlds: WordPress as a CMS, a modern frontend of your choice. In practice, most headless WP projects hit the same walls six months in. After running two of them to production, here are the honest tradeoffs and the patterns that kept me from regret.

The Tradeoff in Plain Terms

You trade a cohesive editing experience for frontend freedom. In classic WordPress, clients see a preview that looks like the live site. In headless, previews require wiring Next.js preview routes to WordPress's preview endpoints. It works. It is not free.

The question is whether the frontend freedom is worth the editing friction. For a content-heavy marketing site with complex design needs, usually yes. For a blog where the default theme would have done fine, usually no.

The Patterns That Held

Treat WP as a JSON API, not a CMS. Use the REST API or WPGraphQL and pretend WP is a backend service. The second you write theme templates, you are bridging two worlds and debugging both.

Cache aggressively on the frontend. WordPress is not built for serving high-volume API calls. A Vercel or Cloudflare layer between your site and WP absorbs the load and keeps WP's database from being the bottleneck.

Own the preview path. Build preview routes on day one, not at the end. Clients who cannot preview a draft will revolt. Plugin-based preview shortcuts have broken on me across WP upgrades; custom routes based on documented preview tokens are durable.

The Pieces You Need

WordPress:
  - REST API enabled
  - Custom endpoints for anything not trivial
  - Preview token generation
  - ACF Pro or native fields for structured content
 
Next.js:
  - Server components fetching WP
  - ISR with revalidate on publish webhook
  - Preview route consuming the token
 
Plumbing:
  - Webhook from WP to Vercel on post update
  - revalidatePath in the webhook handler

Each piece is boring on its own. The value is in the wiring.

When I Say No to Headless

If the client has no in-house developer, headless is usually wrong. They cannot maintain two stacks. Classic WP with a well-built theme serves them better. If the client is an ecommerce site running WooCommerce, classic is nearly always the right answer; headless WooCommerce is still rough. See the WPGraphQL docs for what is actually mature in the headless space.

The Honest Rule

Pick headless when the frontend needs justify the operational overhead of running two stacks. Pick classic when WordPress's default editing experience is already close to what the client needs. Most projects are the second kind.