Skip to content

Migration playbook

WordPress to headless CMS migration

Hard8 to 16 weeks

A guide for publishers and content teams moving off monolithic WordPress to a headless architecture. Headless adds rendering complexity that can wreck indexation if URL preservation, redirects, and metadata mapping are not planned carefully.

Pre-flight

Before kickoff

  • Full URL inventory: export every indexed and indexable URL from Search Console + Screaming Frog.
  • Metadata mapping: which WordPress fields map to which target-CMS fields, including SEO plugin data (Yoast/Rank Math).
  • Redirect plan: every URL that changes needs a 301; every URL that stays needs preserved indexation.
  • Rendering decision: which routes go SSG, ISR, or SSR on the new frontend.
  • Comment, tag, and category strategy: many migrations lose these silently.

If things break

Rollback plan

  • Maintain DNS-level revert path for 14 days post-migration.
  • Keep WordPress origin deployable but unindexed (noindex via robots.txt) for 30 days.
  • Per-section rollback via reverse-proxy routing if one route family fails worse than others.

Steps

Sequenced execution

  1. Step 1

    Set up the target CMS

    Configure Sanity / Contentful / Hygraph with the schema that maps to your current content model. Validate with sample content.

  2. Step 2

    Build the frontend with rendering parity in mind

    Implement canonical generation, OG tags, JSON-LD, sitemap generation matching current behavior. Curl-diff against current site for 100+ URLs.

  3. Step 3

    Migrate content in stages

    Bulk-import content. Validate slug uniqueness and slug history. Preserve publish dates, authors, and modification dates.

  4. Step 4

    Build the redirect map

    For every URL change (slug, hierarchy, structure), create a 301 entry. Verify no chains. Deploy redirects at edge or origin proxy.

  5. Step 5

    Cutover at low-traffic window

    Switch DNS or origin routing. Resubmit sitemap to Search Console immediately.

  6. Step 6

    Monitor and recover

    Indexation drops 5-20% in the first 2-4 weeks are normal. Recovery to baseline typically takes 60-90 days.

Expected metrics

Concrete expectations

Expected downtime
< 30 min (DNS cutover)
Typical rollback time
~ 1 hour (DNS TTL)
Time to indexation recovery
60-90 days
Acceptable indexation drop window
< 20% for first 14-21 days

After cutover

Monitoring discipline

  • Search Console Page indexing — daily for 30 days, weekly for 90 days.
  • Search Console performance — track impressions and clicks at the URL group level.
  • 404 spikes in server logs (or CDN edge logs) — investigate every spike within 24 hours.
  • Sitemap status in Search Console — must show "Success" for the new sitemap within a week.
  • Top-100 query rank tracking via your preferred rank tool — expect 4-8 week recovery curve.

FAQ

Common questions

Should I migrate URL structure during the same release?

Strongly discouraged. CMS migration + URL restructure compounds risk and slows recovery. Migrate the platform first with URL parity, then restructure URLs in a separate release once new-platform baseline is stable.

How do I handle WordPress redirects that rely on plugins?

Export all plugin-managed redirects (Redirection, Yoast, etc.) before cutover. Reimplement them at edge (Cloudflare/Vercel) or in the new framework's redirect config. Plugin-based redirects do not survive migration off WordPress.

What about WordPress media and attachment URLs?

Keep `/wp-content/uploads/` paths if you can — saves a major batch of 301s. Otherwise mirror the image asset paths, deploy 301s for old → new, and resubmit image sitemap.

When can I shut down the old WordPress origin?

Not before 30 days post-migration, and only after redirects are confirmed at edge level. Keep it deployable (with noindex) for an additional 30 days as a recovery option.

Last updated:

Related deep-dives

Get this scoped to your stack

Generic playbooks are useful for orientation; the actual migration plan needs your routes, your CMS, your team capacity. The scoping call is 30 minutes — bring the constraints.

Book scoping callBrowse all migration guides

Other migration guides