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.

DNS layer

Keeping the revert path open for 14 days

The rollback plan above depends on holding a DNS-level revert path while the old WordPress origin stays deployable but unindexed. That is materially easier when records are imported before nameservers move and each name keeps its own origin and Host header. Bridge DNS, the authoritative DNS layer of Bridge CDN, is being built for that shape of cutover. It is pre-launch, with no published SLA.

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