Headless CMS Migration: The Decisions That Cost You Later

Six months after a headless migration, the complaints are never about the technology. They're that publishing a landing page takes four people, the marketing team has gone back to asking engineers for changes, and somebody has started keeping copy in a spreadsheet because the CMS is too awkward to write in.

The build worked and the decisions underneath it didn't, and the ones that hurt are mostly made in the first two weeks, by developers, in a meeting nobody from marketing attended. Most of them live in the content model, which is why that's where a headless CMS migration deserves most of your attention.

Model content by what it is

Of everything Wordify has picked up in ten years of writing for headless CMS vendors (Storyblok, Hygraph, Agility CMS and dotCMS among them), this is the lesson we'd put first, because it costs the most to undo and it's worth getting slowly.

The intuitive way to model content is to mirror what you see, so you get a homepage type with a hero field, a three-column section and a testimonial band. It maps neatly onto the design, everyone understands it immediately, and it rebuilds the page builder you just paid to escape.

The problem shows up the first time you want the same content somewhere else. A customer story modeled as "the testimonial band on the homepage" can't be reused on a product page, syndicated to a partner or pulled into an email, because it isn't a customer story, it's a slot. So you copy it, and then the two copies drift apart.

Model by what things are instead. A customer story is a type with a company, an industry, a quote, a named person and a metric, and where it appears is a separate concern. That feels over-engineered on day one and pays for itself the first time marketing asks for something the original design didn't anticipate, which often happens within a quarter. We like it for a second reason, too, since a required named-person field makes vague, nobody-said-this content much harder to publish, and that's the same instinct behind our primary source content approach, where every claim traces back to a named person.

This advice gets taken too far as well. Split everything into forty types with three fields each and editors have to assemble every page from parts nobody can find, so if a piece of content only ever appears in one place, one field on one type is the right answer.

The fields SEO needs, added now rather than later

Content models get designed by developers working from a Figma file, and Figma files don't come with canonical tags (no shade to the designers, that was never their job).

Every page type needs a title tag that's separate from the H1, a meta description, a canonical URL, a social share image and a place for structured data, all as first-class fields that editors can change, not values derived or computed from other fields. When those fields get designed without anyone from SEO in the room, you end up with no canonical field, nowhere for structured data to live, and a title pulled from the H1 because it seemed reasonable at the time.

That last shortcut is the most common one, and it's wrong for a specific reason. The H1 is written for a reader who has already arrived, while the title tag is written for someone scanning a page of results who hasn't, and those two jobs need different sentences. Google's documentation on title links is worth reading before the model gets signed off, because it explains that Google builds each result's title from sources including the title element, the main heading and og:title, and that when it detects a problem it may generate its own from on-page text or links.

Adding these fields later is a schema change plus a backfill of every existing entry, which is the kind of task that slips down the backlog forever.

Decide rendering per content type, before the build

Headless separates content from presentation, so how your pages get turned into HTML is now your team's decision, and it's the single biggest SEO consequence of the project.

Static generation, where pages are built into plain HTML each time you publish, is the right default for marketing sites and blogs, because content changes rarely enough that a rebuild on publish is fine. Server rendering, where the HTML is built on each request, earns its extra cost where content is personalized or changes by the minute. Client-side rendering, which is what a plain React single-page app does, sends crawlers an empty page and a stack of scripts and leaves them to build it, which Google does on a delay and AI crawlers don't do at all. We've laid out the crawler evidence, and a two-minute test you can run on staging, in CMS migration SEO: what breaks and when.

Pick one approach per content type, write it down, and hold every later phase to it.

Editor experience is where headless migrations stall

The business case for headless usually includes marketing moving faster, and if the result is that publishing needs a developer, you've spent the budget and made the original problem worse. That happens when the model is too fragmented, when previews don't work, or when there's no way to see an unpublished page in context before it goes live.

Test it before launch by sitting a marketer down and asking them to publish a page they've never published, without help, while you watch. Whatever they get stuck on is what will be blocking you in month four.

Sequencing that keeps failures small

Big-bang migrations are attractive because they end, and they're also the version where every problem surfaces at once and none of them are attributable.

Google's site move guide recommends moving small and medium sites all at once, and says larger sites can move a section at a time because it makes problems easier to spot and fix. If your site is big enough for that, start with a section that matters commercially but isn't your highest-traffic area, so the first move teaches you something without being expensive if it goes wrong, then watch it for a month before moving the next.

A phased move costs more engineering time in total, and on a large site we recommend it anyway, because a section-sized failure is diagnosable and a site-sized one is a crisis. Keep two things consistent across every phase, the URL structure (so you're not redirecting twice) and the rendering approach (so you don't end up with half the site invisible to crawlers and no obvious reason why).

Test the model against year two before anyone writes code

A headless migration is won or lost in the content model, so settle the model before the build starts.

Before the first ticket gets written, list the five things marketing will want to do in year two that they can't do today, and check the proposed model supports all five. If it doesn't, fixing it now is cheaper than at any later point in the project. Building the front end is your developers' job, and if you want the search side handled alongside the build, the URL mapping, content triage and crawl monitoring, that's what our SEO migration agency work is for. You can book a discovery call to talk the plan through first.

Andres Phillips, Head of Content at Wordify

When Andres isn't watching his beloved Italian soccer team, AC Milan, he's building winning SEO strategies for SaaS companies.