Headless WordPress with Next.js vs a full migration: how to choose

Once Next.js is going to render your public site, the next question is what happens to WordPress. You can keep it as a headless CMS, retire it completely, or run both and move one section at a time.

The short answer: keep WordPress headless if your editors or a plugin-driven feature cannot move; migrate fully if developers own the content; phase it if the site is too big to freeze.

Each path changes something different: your editors’ day, your security workload, or your launch-day SEO risk. This guide compares them and ends with a rubric you can score for your own site. It is part of our WordPress to Next.js migration guide.

Key takeaways

• Headless WordPress protects the editorial workflow but leaves you running and patching two systems.
• A full migration gives the simplest end state and the biggest change for editors.
• A phased migration spreads risk across months, using Next.js fallback rewrites to forward unmigrated paths to WordPress.
• The usual headless SEO failures are a still-public WordPress front end and canonical URLs that point at the CMS hostname.
• Choose by scoring editor dependence, plugin-driven features, developer capacity and risk tolerance, not by preference for a stack.

Headless, full or phased: the three architectures at a glance

Option 1: headless WordPress with a Next.js front end

Choose headless when the people who publish are the bottleneck you cannot afford to disrupt: a newsroom with daily deadlines, a content team trained on the block editor, or a content model built from dozens of custom post types and ACF field groups that would take months to remodel.

REST API or WPGraphQL?

Both are viable. WPGraphQL’s footing has improved: in 2024 its creator announced it was becoming a canonical WordPress plugin, with Automattic supporting its development. But every plugin in a headless stack is still code exposed to the internet: in 2026 WPGraphQL patched several vulnerabilities, including CVE-2026-40762, an unauthenticated SQL injection fixed in version 2.11.1. The REST API adds nothing beyond core, and its main drawback, over-fetching, is largely solved by _fields, which has supported nested properties since WordPress 5.3.

Make publishing feel instant with on-demand revalidation

Editors expect “Update” to change the live site. Statically rendered pages can be refreshed on demand by calling revalidatePath from a Route Handler (the Next.js tab), and a small must-use plugin can call that handler whenever a post is saved (the PHP tab):

Three details in that hook are easy to get wrong:

• Trashing a post changes its slug first. WordPress appends __trashed before the status hook runs, so the hook strips it, or the deleted post stays live.
• A renamed slug leaves the old URL cached. The post_updated hook refreshes the old path as well.
• The request waits for an answer so a failure is written to the PHP error log instead of vanishing. The cost is up to five seconds on save if the site is unreachable.

Pages outside /blog that list posts, such as the home page or a feed, need their own revalidatePath call. A shared secret compared in constant time is the minimum. Signing the request body and verifying the signature is stronger, and it is what our own site does: its publish webhook checks the CMS’s signature before purging any cache.

Tagging fetches instead of paths? In Next.js 16 revalidateTag takes a second argument: the docs recommend revalidateTag(tag, 'max'), mark the single-argument form deprecated, and suggest { expire: 0 } for a webhook that needs the data gone immediately.

Keep previews working with Draft Mode

Losing “Preview” is the first complaint editors raise about headless setups. Next.js Draft Mode solves it: a secret-protected route turns Draft Mode on and redirects to the page, which then fetches unpublished content. Headless CMS vendors build on the same mechanism; Sanity’s Visual Editing setup for the App Router enables Draft Mode through a route its Studio calls.

The route only switches Draft Mode on. The rest of preview lives on the WordPress side and in one more page:

• Point the Preview button here. Filter WordPress’s preview link so it opens this route with the post ID.
• Fetch the draft, not the post. Edits to a published post are saved as an autosave revision, and the REST API only returns drafts to authenticated requests. A /blog/preview/[id] page should fetch the post’s latest autosave (or the post itself with context=edit) using an Application Password, and only when draftMode().isEnabled is true.
• Keep it out of the index. Mark preview responses noindex.
• Treat the secret as leaked. A secret in a query string ends up in server logs and browser history. Rotate it, or move to short-lived signed tokens.

Headless SEO mistakes to avoid

• A second public copy of your site. WordPress keeps rendering its own theme on its own hostname unless you stop it. Put the CMS behind authentication or an IP allowlist, or at least send X-Robots-Tag: noindex on every front-end response.
• Canonicals that point at the CMS. Yoast adds SEO metadata to standard REST responses through yoast_head_json, canonical included. If WordPress’s site address is the CMS hostname, those canonical and Open Graph URLs will be too. Configure WordPress to use your real domain, or rewrite the hostname when you map the fields.
• Absolute links inside content. Post content often hard-codes the WordPress hostname. Rewrite those links at build or render time.
• The wrong sitemap. Generate the sitemap in Next.js from the URLs it actually serves, and disable or block the WordPress one.

The ongoing cost of two systems

Headless keeps WordPress, so it keeps WordPress’s patching load. Patchstack logged 11,334 new vulnerabilities in the WordPress ecosystem in 2025, 91% of them in plugins and 46% unpatched when disclosed. Hiding the CMS from the public internet narrows the exposure but not the update work. Add the Next.js side, which since July 2026 has pre-announced security releases roughly once a month, and plan for two update cycles.

Option 2: a full migration away from WordPress

Choose a full migration when developers already own the site, the content is mostly articles and landing pages, and retiring WordPress removes a real burden (security updates, hosting, plugin licences) rather than just a technology you dislike.

The cost lands on editors. They move to one of three models:

• Files in Git (Markdown or MDX), edited through pull requests. Simplest and cheapest, but hostile to non-technical editors unless you add a Git-based CMS such as TinaCMS, which keeps content as Markdown, MDX or JSON in your repository and adds visual editing on top.
• A hosted headless CMS such as Sanity, with polished editing and preview, and usage-based pricing.
• A self-hosted headless CMS such as Payload or Strapi, with full control and full operational responsibility.

The best CMS for Next.js compares these in detail. Whichever you choose, the content has to be exported and converted once; how to export WordPress to MDX covers that pipeline.

Option 3: a phased migration on one domain

A phased migration runs both stacks on one domain. Next.js serves what has been rebuilt and forwards every other request to WordPress, so you can move the blog first, then landing pages, then the rest, with a smaller URL change at each step.

Next.js documents this as incremental adoption. Its fallback rewrites are applied after dynamic routes and all static assets have been checked, just before the 404 page, so you can proxy everything Next.js does not handle to the old site without touching the config each time a section moves:

Four things to know before you rely on it:

• Fallback only catches paths no route matches. A root-level dynamic segment such as app/[slug]/page.tsx, or a section route that calls notFound() for posts it has not migrated yet, answers with a 404 and never reaches WordPress. Avoid root-level dynamic segments during the migration, and move a section only when every URL in it exists in Next.js.
• Keep WordPress from redirecting. That is why the page rule adds the trailing slash and files get a rule of their own: when we tested the plain /:path* form, WordPress answered /old-page/ with a redirect to its own hostname and the visitor left the site. For any redirect WordPress still issues, map X-Forwarded-Host in wp-config.php, trusting it only from your proxy, so the Location header names the public domain.
• Do not proxy the admin. A catch-all also forwards /wp-admin/, /wp-login.php, /xmlrpc.php and /wp-json/ onto your public domain. Return a 404 for those paths in Proxy.
• Test with and without a trailing slash, on the public domain, and check every response comes back on it.

What makes phased migrations go wrong is inconsistency between the two stacks:

• The legacy origin must not be indexable on its own hostname, but a rewrite passes the origin’s response headers straight through, so a blanket X-Robots-Tag: noindex would deindex every proxied page on the public domain too. Make it conditional: have Proxy add a secret request header to proxied requests, and have WordPress send noindex only when that header is missing. Check both hostnames with curl -I.
• WordPress must think it lives on the public domain, so its canonical tags, internal links and Open Graph URLs point there.
• Shared chrome drifts. Header, footer, navigation, consent banner and analytics now exist twice. Change both or visitors will notice the seams.
• One sitemap index should list the URLs each stack serves, updated as sections move.

Define the exit criteria up front: when the last section moves, remove the fallback rewrite and retire the legacy origin. Phased migrations that never finish leave you paying for both stacks indefinitely.

Score your own situation

Score each criterion from 1 to 5, where 1 means it strongly favours a full migration and 5 means it strongly favours headless. Multiply each score by its weight and add them up. The total runs from 14 to 70: above 46 points to headless, below 38 to a full migration, and anything in between is close enough to decide on cost, or to phase.

If plugin-driven functionality scores 4 or 5, look hard at a phased approach: move the content-heavy sections to Next.js and leave the functional parts (a WooCommerce store, an LMS) on WordPress until their replacements are properly scoped.

Scores close, or not sure how to rate a row? In a free 15-minute audit we look at your site with you on a live screen-share and tell you which path we would take and why.

What we chose for our own site

This site runs the full-migration end state: Next.js on Vercel, content in Sanity, three domains served from one deployment, and a publish webhook that refreshes cached pages when an editor publishes. For clients we usually recommend the same when their team is ready to leave WordPress, as ProEd did, and a headless or phased route when a plugin-driven feature has to keep running.

More in this series

• WordPress to Next.js migration: the complete guide
• Next.js redirects for WordPress URLs: 308s, query strings and scale
• Export WordPress to MDX: blocks, shortcodes and ACF fields
• Best CMS for Next.js: seven options compared
• Website migration SEO checklist: 30 days before launch to day 90

Ready to choose a path?

Fill in the rubric above with whoever owns your content. Ten minutes together will settle more than a week of debate about stacks.

Lunova Labs builds headless and fully migrated Next.js sites, and will tell you honestly which one your site needs.