WordPress to headless CMS: the SEO migration playbook

Every CMS migration has the same dirty secret: the technology part is the easy part. Re-platforming from WordPress to Contentful, Sanity, Payload, or Strapi is a well-documented engineering exercise. What's poorly documented — and what actually determines whether the migration succeeds or fails from a business perspective — is the SEO migration running alongside it.

This playbook covers the SEO workstream for a WordPress-to-headless migration. It assumes you've already decided to migrate (this isn't an argument for or against headless) and that you're comfortable with the technical SEO fundamentals covered in the Headless CMS SEO guide. What it provides is the step-by-step audit-redirect-validate loop that protects your rankings through the transition.

Why CMS migrations are SEO-dangerous

The reason CMS migrations damage rankings isn't mysterious. It's mechanical. Google has indexed your current URLs, associated them with content, assigned them authority based on links and engagement signals, and ranked them accordingly. A migration changes some or all of the following:

• URL structures. WordPress uses /year/month/slug/ or /category/slug/ patterns by default. Headless frontends typically use /slug/ or /section/slug/. Every URL that changes needs a redirect.
• Rendering method. WordPress serves fully-rendered HTML. A headless frontend might use client-side rendering, server-side rendering, or static generation — each with different SEO implications.
• Internal linking. WordPress auto-generates category pages, tag pages, author archives, and date archives. These pages have internal links and sometimes rankings. A headless frontend won't recreate them unless you explicitly build them.
• Structured data. WordPress SEO plugins (Yoast, Rank Math, All in One SEO) generate structured data automatically. In a headless setup, structured data is your responsibility.
• XML sitemaps. Same as above — WordPress plugins handle sitemap generation. Your new frontend needs its own implementation.

The risk isn't that any one of these changes is hard to manage. The risk is that all of them happen simultaneously, and the ones you forget about are the ones that cause traffic drops. For a broader look at auditing headless sites, the headless CMS SEO audit guide covers the post-migration state in detail.

Prerequisites

Before starting the migration SEO workstream:

• Access to the current WordPress site. Admin access, or at minimum access to the WordPress database export and the live site's HTML output.
• A crawl of the current site. You'll need a complete URL inventory. An Evergreen free account handles up to 500 pages — sufficient for most small-to-mid sites. For larger sites, the Pro tier covers up to 25,000 pages.
• Google Search Console access. You need the performance data (clicks, impressions, CTR, position) for the current domain.
• Google Analytics access. GA4 traffic data by landing page for the past 12 months minimum.
• A staging environment for the new site. The headless frontend should be crawlable in staging before you go live.

The migration SEO workflow

This is the sequence. Steps are ordered by dependency — you can't do step 3 without completing step 2, and skipping step 1 is how migrations fail silently.

Step 1: Baseline audit of the WordPress site

Before touching anything, document what you have. This baseline is your insurance policy — it's what you compare against after migration to verify nothing was lost.

Crawl the entire site. Capture every URL, its HTTP status code, title tag, meta description, H1, canonical tag, and internal link count. Export this as your pre-migration URL inventory.

Export Search Console data. Pull the last 12 months of performance data at the page level: URL, clicks, impressions, average position, average CTR. Sort by clicks descending. The top 50 pages by organic traffic are your critical pages — these get individual attention during migration.

Export GA4 landing page data. Pull sessions by landing page for the past 12 months. Cross-reference with GSC data to identify pages that get traffic from both organic and non-organic sources.

Document WordPress-generated pages. WordPress creates pages you may not think of as "content" but that Google has indexed:

• Category archive pages (/category/[name]/)
• Tag archive pages (/tag/[name]/)
• Author archive pages (/author/[name]/)
• Date archive pages (/2024/03/)
• Paginated pages (/blog/page/2/)
• Media attachment pages (/?attachment_id=123)
• Search result pages (/?s=query)

Check Google Search Console's index coverage report to see which of these Google has actually indexed. Indexed pages with traffic need redirects. Indexed pages without traffic can usually be redirected to their parent or dropped with a 410 status.

Capture structured data. Use Google's Rich Results Test on your top 20 pages. Document what schema types are present (Article, BreadcrumbList, FAQPage, Organization, etc.). Your new frontend needs to replicate these.

Screenshot key pages. Take screenshots of your top 10 pages showing their rendered state — title, meta, canonical, Open Graph tags, structured data output. These become your verification reference post-migration.

In Evergreen, the content audit table gives you the URL inventory, metadata, and internal linking data in a single view. Filter to pages with the most inbound internal links to identify structurally important pages you might otherwise overlook.

Step 2: URL mapping and redirect strategy

This is the step that determines migration success or failure. Every URL on the old site needs a destination on the new site or an explicit decision to not redirect.

Build the URL map. Create a spreadsheet or structured file with four columns:

Rules for the URL map:

1. Every page with organic traffic gets a 301. No exceptions. Even 5 monthly clicks compound.
2. Every page with external backlinks gets a 301. Check your backlink profile. Pages with links from other sites carry authority you don't want to lose.
3. Category and tag archives with traffic get 301s. Redirect to the closest equivalent on the new site, even if it's a filtered view.
4. Author archives usually get 410s unless the author has a meaningful following that drives direct traffic.
5. Date archives get 410s. Nobody searches for /2024/03/ and Google doesn't weight these.
6. Media attachment pages get 301s to the post they belong to. WordPress creates individual pages for uploaded images — these occasionally accumulate links.

Implement redirects at the infrastructure level, not the application level. Use your hosting provider's redirect rules (Vercel vercel.json, Netlify _redirects, Cloudflare Workers) rather than the headless CMS or frontend framework. Infrastructure-level redirects are faster and survive application changes.

// vercel.json redirect example
{
  "redirects": [
    {
      "source": "/2024/:month/:slug",
      "destination": "/blog/:slug",
      "statusCode": 301
    },
    {
      "source": "/category/:name",
      "destination": "/blog?category=:name",
      "statusCode": 301
    }
  ]
}

Use regex patterns for systematic URL changes. If WordPress used /year/month/slug/ and the new site uses /blog/slug, a single regex handles hundreds of redirects. But test the regex against your full URL inventory — a greedy pattern can accidentally match URLs you didn't intend.

Step 3: Pre-launch validation on staging

Before going live, crawl the staging site and verify the critical elements.

Crawl the staging frontend. Compare the staging crawl against your baseline WordPress crawl. Check:

• Do all critical pages exist at their new URLs?
• Do 301 redirects resolve correctly? (Test a sample of 20–30 from your URL map.)
• Are title tags, meta descriptions, and H1 tags present and correct?
• Is the canonical tag pointing to the correct new URL (not the old URL, not the staging URL)?
• Is the XML sitemap present and listing only the new URLs?

Verify rendering. If your headless frontend uses client-side rendering for any content, check whether that content is visible to crawlers. Use Google's URL Inspection tool once the site is live, or use a headless browser (Puppeteer, Playwright) in staging to compare the initial HTML response with the fully-rendered DOM. Content that only appears after JavaScript execution may not be indexed. The JavaScript rendering audit checklist covers this in detail.

Verify structured data. Run Rich Results Test on your top 20 pages in staging. Compare output against your baseline screenshots from Step 1. Every schema type that existed on WordPress should exist on the new site.

Verify internal linking. A headless frontend won't recreate WordPress's automatic internal linking (related posts, category widgets, breadcrumbs) unless you build it. Compare the internal link count per page between old and new crawls. Pages that lost significant internal links need attention.

Check robots.txt and meta robots. Staging sites often have noindex directives or robots.txt blocks to prevent Google from indexing the staging environment. Verify these will be removed at launch. This is the most common "obvious" mistake — and it happens on roughly one in five migrations because the launch checklist doesn't include it.

Step 4: Launch and post-migration validation

The launch itself should be fast — DNS change, redirect activation, robots.txt update, sitemap submission. The validation after launch is where the real work is.

Immediately after launch:

1. Submit the new XML sitemap to Google Search Console.
2. Use the URL Inspection tool to request indexing on your top 10 pages.
3. Test 30–50 redirects manually. Check for redirect chains (old URL → intermediate URL → final URL) — these should be direct 301s.
4. Verify the old robots.txt is no longer being served.

Week 1 monitoring:

• Check GSC index coverage daily. Watch for spikes in "Excluded" or "Error" pages.
• Monitor organic traffic in GA4. A 10–20% dip in the first week is normal as Google recrawls. A 50%+ drop means something is broken.
• Crawl the live site and compare against the staging crawl. The numbers should match.
• Check for 404s in GSC. Any 404 on a page that had traffic is a redirect you missed.

Week 2–4 monitoring:

• Traffic should begin recovering to pre-migration levels. Full recovery typically takes 4–8 weeks for sites with less than 1,000 pages, and 8–16 weeks for larger sites.
• Monitor for position changes on your critical keywords. Some fluctuation is expected — a sustained drop on a specific keyword indicates a problem with that page specifically.
• Check for soft 404s — pages that return a 200 status code but display error content. These are common when headless frontends serve a generic "page not found" component without setting the proper HTTP status.

Step 5: Rollback planning

Every migration needs a rollback plan, and the plan needs to be documented before launch — not improvised during a traffic emergency.

The rollback trigger: Define in advance what constitutes a rollback-worthy event. A reasonable threshold: organic traffic drops more than 40% from the baseline for three consecutive days with no recovery trend, AND the cause cannot be identified and fixed within 24 hours.

The rollback process:

1. Revert DNS to point back to the WordPress installation (which should remain running in read-only mode for at least 30 days post-migration).
2. Remove the new site's redirects.
3. Resubmit the original XML sitemap to GSC.
4. Investigate the failure before attempting the migration again.

Why rollback is rarely needed: Most migration SEO failures are caused by missing redirects, blocked crawling, or broken rendering — all fixable without rolling back. True rollbacks are for catastrophic failures where the new frontend is fundamentally broken in ways that can't be patched quickly.

Reading the post-migration data

The data you collect in the weeks after migration tells a specific story. Here's how to read it.

Traffic dip followed by recovery (the normal pattern): Google is recrawling the site, processing redirects, and reassigning signals. This usually completes within 4–8 weeks. No action needed unless specific pages are underperforming.

Traffic dip with no recovery after 4 weeks: Something structural is wrong. Common causes: redirect chains adding latency, JavaScript rendering blocking content from indexation, canonical tags pointing to wrong URLs, or internal linking density significantly lower than the old site.

Specific pages dropped while the rest recovered: The problem is page-specific. Check the redirect for that URL, verify the new page's content matches the old page's content closely enough, and confirm the new page has equivalent internal linking.

Indexation declining over time: Google is discovering pages it can't render or that return errors. Check server logs for Googlebot requests and verify they're getting 200 responses with fully-rendered content. This is especially common with client-side rendered headless setups.

How Evergreen streamlines the migration audit

The pre-migration baseline and post-migration comparison are the two most labor-intensive parts of this process. In Evergreen, both are handled by the same crawl-and-audit infrastructure.

Before migration: Crawl your WordPress site in Evergreen. The content audit table captures every URL with its title tag, meta description, H1, canonical tag, internal link count, and HTTP status. This is your baseline — filterable, sortable, and permanently stored.

After migration: Crawl the new headless frontend. Compare the two crawls side by side. Pages that lost metadata, changed status codes, or dropped internal links surface immediately in the audit table. You don't need to manually diff spreadsheets — the comparison is structural.

If you've connected GA4 and GSC to Evergreen, traffic data overlays onto the audit view. You can filter to pages that had organic traffic on the old site and verify their new URLs are indexable and performing. The guide to combining GA4 and Search Console data covers this workflow in detail.

For agencies managing multiple client migrations, shareable audit reports let you send pre-migration and post-migration snapshots to clients without requiring them to log in. The shareable SEO reports guide covers this workflow.

Audit before and after — for free. Start free →

Related resources

• Headless CMS SEO: the complete guide — the parent pillar covering all headless CMS SEO fundamentals
• Headless CMS SEO audit: the vendor-neutral guide — detailed post-migration audit methodology
• Payload CMS SEO: the complete third-party guide — platform-specific guidance for one of the most common migration targets
• Technical SEO audit guide for headless websites — broader technical audit coverage for headless architectures