January 8, 2026
By Marcus Feldt
7 min read
What we learned rebuilding forty sites on a headless CMS
Four years, forty migrations, and a short list of things we would do differently on every one of them.
Four years, forty migrations. Headless was the right call almost every time, and almost every project still hit the same three walls.
The editor is the product
Teams do not experience a CMS through its API; they experience it through the screen where they add a page. If that screen shows forty fields with no order and no help text, the site will fill up with empty sections and duplicated pages inside a month. We now spend as long designing the editing screens as the public ones.
A migration succeeds when the marketing team stops asking us to publish things for them.
Preview is not optional
The single most common reason a headless project stalls is that nobody can see a change before it is live. Budget for preview from the start; retrofitting it costs more than building it.
Model the content, not the page
The strongest migrations described what things *are* — a programme, a case study, a person — rather than where they sit on a layout. Those models survived two redesigns. The ones modelled as "homepage block one" had to be rebuilt the first time the homepage changed.