Migrating an Existing WordPress Site to Headless

In a traditional WordPress site, the theme and plugins build the HTML. When the front end moves to a framework such as Next.js, none of that output comes along automatically. SEO plugins stop printing meta tags and schema, form plugins stop rendering forms, shortcodes appear as raw text and redirection plugins no longer intercept requests on the new front end.

Start by listing every plugin and theme feature that affects what a visitor or crawler sees. Go page type by page type: home, posts, pages, archives, search, products, forms and landing pages. For each, record the meta tags, structured data, scripts, shortcodes, blocks and redirects involved. This list becomes the scope of the migration, and it is usually longer than anyone expected.

• SEO metadata, canonical tags and structured data from the SEO plugin
• Forms, search, comments and any interactive features
• Shortcodes and custom blocks used in content
• Redirects, tracking scripts, consent banners and cookie behaviour

The safest migration is one where search engines barely notice. Keep every public URL exactly the same, including trailing slashes, category bases, pagination formats and file extensions. Google's guidance on site moves makes the same point: when URLs change, each old URL needs a permanent redirect to its new equivalent, and rankings can fluctuate while Google processes the change.

Keep titles, meta descriptions, headings, canonical tags, hreflang, structured data and internal links equivalent too. A headless rebuild is a tempting moment to redesign the information architecture, but combining a platform change with a URL change makes it much harder to tell what caused any drop in traffic. Change the platform first; restructure later, separately. The site migration guide covers redirect mapping in detail.

The technique that makes a staged migration possible is a routing layer in front of both systems. The domain points at the new front end or at a CDN or reverse proxy. Paths that have been migrated are served by the new front end; everything else is passed through to the existing WordPress theme, which keeps running unchanged on a separate hostname.

In Next.js this can be done with rewrites that send unmatched paths to the WordPress origin. A CDN or a reverse proxy such as Nginx can do the same with path rules. Either way, visitors and crawlers see one site on one domain. Make sure cookies, redirects, sitemaps, robots.txt and the WordPress admin and preview routes are handled deliberately, and that the old origin is not separately indexable under its own hostname.

Choose the first section for low risk and clear value: often the blog, a set of landing pages or a documentation area with simple templates and few interactive features. Migrate it, check it thoroughly, switch its paths over in the proxy, then watch traffic, errors and Search Console for a couple of weeks before moving on.

Leave the most complex areas, such as checkout, accounts, search and anything with heavy plugin dependencies, until last, or decide that they stay on traditional WordPress. A hybrid site is a legitimate end state. On the Healthus.ai migration of 69 legacy PHP landing pages to a Next.js front end backed by WordPress, my part was the content architecture and REST API layer, and extracting every FAQ, statistic and asset into structured mappings is what made page-by-page comparison possible. The case study describes that contribution.

Before each section goes live, compare the new pages with the old ones automatically. A script that fetches both versions of every URL in the section and compares status codes, titles, meta descriptions, canonical tags, robots directives, headings, structured data and internal links will catch most regressions. Check that the main content is in the initial HTML, not only rendered in the browser.

Test the edges as well: unknown URLs should return a real 404 status, not a 200 page that says not found; redirects should still fire; pagination and archives should match; the sitemap should list the migrated URLs; and previews should work for editors. The headless SEO checklist lists the items worth automating.

With a proxy in place, each cutover is a routing change, not a deployment of a whole new site. That makes rollback simple: switch the paths back to WordPress. Write the rollback steps down before the cutover, test them on staging and agree who decides to use them and on what evidence, such as error rates, conversion drops or crawl errors.

Schedule cutovers for a quiet period, purge caches deliberately and watch server logs, real-user monitoring and Search Console coverage in the following days. Keep the old templates working until the new section has been stable for some time.

Editors keep using the WordPress admin, but some things change. Preview needs to be wired to the new front end, or editors will see the old theme or nothing at all. Published changes may take a moment to appear if the front end uses static generation or incremental regeneration. Blocks and shortcodes that the new front end does not support will look wrong.

Agree these details with the editorial team before cutover, document how publishing now works and give them a way to report problems. The headless versus traditional guide and the preview setup guide cover the editor experience, and the headless WordPress service explains how I plan migrations.