Nobody tells you how emotionally attached you get to WordPress until you're mid-migration and everything is broken and you're seriously considering just keeping it.
We've been there. And we've helped clients through it. So here's the honest, unfiltered account of what a WordPress to headless CMS migration actually looks like — the wins, the pain, and what we'd do differently.
Why We Left WordPress in the First Place
WordPress powers about 43% of the internet. That stat gets thrown around a lot, usually by people trying to convince you it's still the right choice.
Here's what that stat doesn't tell you: most of those sites are running themes from 2017, plugins that haven't been updated in two years, and a page builder that slows the frontend to a crawl.
For content-heavy sites that need to perform — fast load times, clean API delivery, structured data — WordPress starts feeling like you're building a race car with a lawnmower engine underneath.
The specific breaking points for us:
- The REST API output was a mess. Nested HTML inside JSON. Inconsistent field names. No schema to depend on.
- The frontend was coupled to WordPress whether we wanted it to be or not.
- Every plugin update was a potential fire.
- Multilingual support required two plugins that hated each other. We knew it was time.
Phase 1: Choosing the New CMS
This is where most teams spend too long. The options are genuinely good and genuinely different — Contentful, Sanity, Strapi, and newer platforms like Contensa that take a different approach entirely.
We evaluated on three criteria:
1. How fast can we model our content? We had 14 content types across the old site. Rebuilding those schemas from scratch in a new system is tedious. Contensa stood out here because you describe your content in plain English and it generates the model for you. That alone saved us probably 12 hours.
2. How clean is the API? We were building a Next.js frontend. The API needed to be predictable, typed, and fast. GraphQL support was a must.
3. How will editors handle it? The client's editorial team had zero technical background. If the interface wasn't intuitive, we'd be fielding support tickets forever.
Phase 2: Exporting WordPress Content (The Fun Part — Just Kidding)
WordPress exports via XML. If you've ever opened a WordPress XML export, you know it's one of the more depressing documents a developer can encounter.
Every post, page, and custom post type is in there, along with metadata, serialized PHP arrays, shortcode markup, and media attachments that may or may not still exist.
Our migration script:
- Parse the XML export
- Strip shortcodes and embedded HTML formatting
- Map WordPress fields to new content type fields
- Convert content to clean Markdown
- Import via API into the new CMS Step 4 is where most of the work lives. WordPress rich text is full of div soup. Getting clean, structured content out of it requires patience.
Phase 3: The Frontend Rebuild
This is actually the part most developers enjoy. Once the content is structured and the API is clean, building the frontend is fast.
With Next.js and a GraphQL endpoint, we were fetching exactly the data we needed, nothing more. No loading unnecessary fields. No parsing HTML embedded in JSON responses.
Page speed scores went from the mid-60s to the high 90s. Not because we did anything fancy — just because structured content delivered via API is inherently faster than WordPress rendering HTML on the server.
What We'd Do Differently
Start content modeling earlier. We jumped into the migration before fully mapping out the new content model. We ended up restructuring two content types mid-migration.
Plan for media from day one. WordPress media URLs are all over the content. We had to do a second pass to migrate all media assets to the new CMS and update references.
Use a CMS that accelerates the schema phase. Tools like Contensa that generate your content model from a description cut setup time dramatically. On a migration project, that matters.
Was It Worth It?
Yes. Every time.
The WordPress site needed constant maintenance. The headless setup runs quietly, loads fast, and gives the editorial team a clean interface to work in.
If you're on the fence about migrating, the question isn't whether it's worth it. The question is how much longer you're willing to pay the WordPress tax.
Top comments (0)