Migrate WordPress to headless without losing SEO

You keep your search traffic in a WordPress to headless move by changing as little as possible that Google can see: the same URLs where you can, a permanent redirect for every URL that has to change, and the same titles, headings and structured content on the new pages. Everything else in this checklist serves those three rules.

Google describes the process for a move with URL changes in its documentation: map old URLs to new ones, redirect permanently, submit a new sitemap, and monitor. This post turns that into a working order of tasks.

What should I inventory before touching anything?

Build a complete list of every URL that exists today and every URL that matters. Google suggests finding important URLs through your sitemaps, server logs and analytics, and that is a sensible start.

Collect, and keep in one spreadsheet:

1. Every URL in the current XML sitemap.
2. Every URL that received visits in your analytics over a long period (a year is better than a month, because seasonal pages hide).
3. Every URL that has backlinks or appears in Search Console's performance report.
4. A crawl of the live site, so you also catch URLs that are in none of the above: tag and category archives, attachment pages, paginated lists, author pages, PDFs and uploaded files.
5. For each URL: title, meta description, H1, canonical, robots directive, language, and status code.

That last item is your parity baseline. Without it you cannot prove later that nothing changed. Save the crawl file with a date in its name and do not overwrite it.

How do I build the redirect map?

A redirect map is a two-column list: old URL, new URL. Every old URL from the inventory gets a row. The new URL should be the closest equivalent page, not the home page.

Rules we would follow:

• If the URL can stay the same, keep it. The best redirect is the one you never need. Headless does not force you to change slugs.
• Use permanent redirects for pages that moved for good. Google recommends HTTP permanent redirects (301 or 308) if possible.
• Avoid chains. Google advises avoiding more than three hops where feasible; aim for one hop, old URL straight to final URL. Remember to include the http to https and www variants in the map.
• Do not use JavaScript redirects for this. Google warns that rendering can fail, so a JavaScript redirect might never be seen.
• If an old page has no equivalent, let it return a real 404 or 410 rather than redirecting everything to the home page. Redirect to a page that does not match the old content only confuses users.

In Next.js, redirects live in next.config.js. With permanent: true the framework sends a 308, which is a permanent redirect. A pattern covers a whole section:

module.exports = {
async redirects() {
return [
{
source: '/old-blog/:slug*',
destination: '/blog/:slug*',
permanent: true,
},
]
},
}

For a long list of one-off URLs, generate the array from your spreadsheet instead of typing it by hand, and keep the source file in the repository so the redirect map is versioned.

What has to match on the new pages?

Metadata parity means the new page tells Google the same thing the old page did, unless you changed it on purpose. Compare these fields, page by page, against your baseline crawl:

• Title tag and meta description
• H1 and the heading structure below it
• Main body text and image alt text
• Canonical URL (self-referencing, absolute, and pointing to the new URL)
• Robots directives (a stray noindex is the classic launch-day accident)
• Structured data, if the old site had it from a plugin
• Internal links, updated to point directly to the new URLs so they do not pass through redirects
• Language and hreflang annotations, if the site is multilingual

WordPress SEO plugins often generate things you never wrote yourself: canonicals, sitemaps, breadcrumbs markup, robots.txt rules, social preview tags. List what the old plugin produced by looking at the rendered HTML, and make sure the new build produces the equivalent.

How do I test before launch?

Test on a staging site that Google cannot reach. Google's documentation recommends password protection for staging sites rather than relying on a noindex tag. Note also that a robots.txt block stops Google from seeing a noindex tag at all, so do not rely on the two together.

On staging, run this sequence:

1. Crawl staging with the same tool you used on the live site.
2. Compare the two crawls: titles, descriptions, H1s, canonicals and status codes, row by row. Differences should be only the ones you decided on.
3. Feed every old URL from the redirect map to staging and check that each returns one permanent redirect to the expected page with a 200 at the end.
4. Check that the new sitemap lists only final, indexable, 200 URLs, with absolute addresses.
5. Check that no staging address appears in canonicals, sitemaps or links.
6. Check the pages with forms, search and any plugin features that had no direct replacement.

What do I do on launch day and after?

Launch day:

1. Point the domain at the new production site. Staging stays password protected and is never opened to the public.
2. Confirm production has no noindex directive and that robots.txt allows crawling.
3. Run the redirect test again against production.
4. Submit the new sitemap in Search Console. Google says this helps it learn about the new URLs.
5. Inspect a handful of key URLs with the URL Inspection tool.

If the domain itself changes (for example from oldname.com to newname.com), also use the Change of Address tool. If the domain stays the same, you do not need it. Google says it is not needed for HTTP to HTTPS moves, www to non-www switches, or path changes within the same domain.

Over the next weeks:

• Watch the Page indexing report and the Sitemaps report for new errors.
• Compare impressions and clicks per page group against the weeks before the move. Expect some movement while Google re-processes the site; investigate a page that stays down rather than the whole site.
• Fix internal links that still go through a redirect.
• Keep the redirects. Google's guidance is to keep them for as long as possible, generally at least one year.

Whether any individual rankings move after a migration depends on the site, and nobody can promise you none will. What you can control is that every difference is one you chose.

When this is not for you

Do not migrate off WordPress just because headless is fashionable. If your site is a brochure with a blog, your editors are happy, and the site is fast and maintained, the migration is a cost and a risk with no search benefit. We would also not migrate in the weeks before your busiest season, and we would not take the job if you cannot give us access to the current analytics and Search Console, because then there is no baseline to protect.

Migration makes sense when WordPress has become the problem: plugin sprawl, security upkeep you cannot sustain, or content that needs to feed an app or a store as well as a website.

Next step

If you are weighing a move and want a second opinion on the URL inventory and risks, book a free call with Kevin. We build on Next.js and Payload CMS, and the code is yours. See also our website development work, or go straight to contact.