Prompt
How do I migrate from WordPress to a headless CMS without breaking URLs?
Latest observation
To migrate from WordPress to a headless CMS without breaking URLs, the key is to preserve your existing URL structure and set up a clean redirect strategy for anything that changes.
1) Audit your current URLs
Export or crawl your WordPress site and make a list of:
- Post URLs
- Page URLs
- Category/tag URLs
- Author archives
- Media/file URLs
- Any custom post type URLs
- Old URLs that already redirect or 404
This becomes your migration map.
2) Keep the same URL patterns if possible
The easiest way to avoid broken links is to make the new frontend match WordPress URL patterns.
Examples:
- WordPress post:
/blog/my-post/ - New site should also use:
/blog/my-post/
If you can preserve:
- slugs
- URL nesting
- trailing slash behavior
- category paths
you’ll avoid most redirects.
3) Create a URL mapping table
For every WordPress URL, define:
- old URL
- new URL
- status: same / redirected / retired
Example:
| Old URL | New URL | Action |
|---|---|---|
/about/ | /about/ | keep |
/2019/08/my-post/ | /blog/my-post/ | 301 redirect |
/category/news/ | /news/ | 301 redirect |
This is essential for preserving SEO and preventing broken links.
4) Set up 301 redirects
If any URL changes, use 301 redirects from old to new.
Where to implement them:
- CDN / edge layer
- Nginx / Apache
- Next.js / Nuxt / Remix redirects
- Cloudflare redirects
- Hosting platform rules
Avoid relying only on WordPress redirects after decommissioning WP.
5) Keep slugs identical during migration
When importing content into the headless CMS:
- preserve post slugs
- preserve published dates if they affect URL structure
- preserve category slugs if used in paths
- preserve media file names/paths where possible
If you change slugs, you must redirect each old URL.
6) Handle media carefully
WordPress media URLs often appear in:
- blog content
- image tags
- PDFs
- embedded downloads
Options:
- keep the same file paths on your new host/CDN
- or migrate media and redirect old file URLs
- update content references during import
If possible, keep old media URLs working indefinitely.
7) Mirror metadata and canonical tags
To avoid SEO issues:
- keep page titles and meta descriptions where possible
- set canonical URLs to the new live URL
- ensure internal links point to the new URLs, not old WordPress URLs
- regenerate XML sitemaps for the new site
8) Test before launch
Before switching DNS or going live:
- crawl the staging site
- verify every important old URL redirects correctly
- check for 404s
- confirm trailing slash behavior
- test query strings and pagination
- validate media links
Useful tools:
- Screaming Frog
- Sitebulb
- Ahrefs / Semrush crawl tools
- Google Search Console after launch
9) Launch in phases
A safe rollout:
- Build the headless frontend
- Import content into the new CMS
- Test URL parity
- Add redirects
- Switch traffic
- Monitor logs and Search Console for 404s
- Fix broken links quickly
10) Keep WordPress available temporarily
If possible, keep the old WordPress site live for a while behind redirects or on a staging subdomain. This helps if you discover missed URLs after launch.
Common pitfalls to avoid
- changing slugs without redirects
- forgetting author/category/tag archives
- losing trailing slashes
- breaking pagination URLs
- not redirecting media files
- changing case sensitivity
- forgetting old campaign or landing page URLs
Best-practice approach
If URL preservation matters most:
- replicate WordPress URL structure in the new frontend
- use 301 redirects only for exceptions
- preserve media paths
- keep a full redirect map
If you want, I can also give you:
- a step-by-step migration checklist,
- a redirect mapping template, or
- an example setup for Next.js + headless CMS + 301 redirects.