Headless WordPress with Next.js: The Parts Nobody Warns You About
The demo is always the same: fetch posts via GraphQL, render them in React. The parts that actually take weeks are preview mode and revalidation.
Tanjil Ahmed
Lead Software Engineer · Notionhive
Headless WordPress tutorials make the integration look trivial: WPGraphQL on the backend, a fetch call on the frontend, done. The tutorials stop exactly where the real engineering starts — the editorial experience that makes a content team willing to actually use the system.
Preview mode is the make-or-break feature
Editors need to see a draft rendered exactly as it will look live, before publishing, without the frontend team in the loop. Wiring Next.js draft mode to WordPress's preview links — with correct auth, correct revalidation scoping, and correct handling of unpublished relationships — takes real effort, and skipping it is the single most common reason a headless migration gets rejected by the content team.
- On-demand revalidation via webhook beats timed revalidation for anything editorial.
- Preview mode needs to bypass the CDN cache entirely, not just the app cache.
- ACF field changes and taxonomy changes both need their own webhook triggers — post save alone isn't enough.
- Budget real QA time for the editorial workflow, not just the rendering layer.
A headless CMS that editors can't preview correctly gets abandoned within a month, no matter how fast the frontend is.