Headless CMS Development
Headless answers a small number of real problems, expensively
Separating content from presentation is the right call for multi-channel publishing, several front ends, or an editorial team large enough to need proper workflow. For a single marketing site with one team, it usually buys complexity and takes away preview.
Plainly
What headless actually means, without the marketing
A traditional content management system stores your content and also renders your pages. A headless one only stores the content and hands it over through an interface, leaving the rendering to whatever you build. That is the entire idea. Everything else attached to the term is a consequence of that separation.
The consequence people want is reuse. Because the content is not tied to a page, the same product description can appear on a website, in an app, on a screen in a shop and in a feed sent to a partner, edited in exactly one place. For an organisation genuinely publishing to several destinations, that is worth a great deal.
The consequence people do not anticipate is transfer of responsibility. A traditional platform quietly handles a long list of things: preview, routing, redirects, pagination, canonical tags, sitemap generation, response codes, search within the site, media handling. In a decoupled build every one of those becomes an item on somebody’s backlog, and each one is small enough to be forgotten and large enough to matter.
Trade-offs
Traditional, headless and the middle ground
| Dimension | Traditional CMS | Headless CMS with a custom front end | Hybrid or decoupled with rendering built in |
|---|---|---|---|
| Content reuse across channels | Awkward — content belongs to pages | The point of the architecture | Possible, with some constraints |
| Editorial preview | Included | Has to be designed and built | Usually included |
| Search and metadata behaviour | Largely handled by the platform and its extensions | Entirely your application’s responsibility | Shared between platform and application |
| Who is needed for a change | An editor for most things | A developer for anything structural | An editor for most things, a developer for the rest |
| Cost profile | Lower to start, licence and plugin costs ongoing | Higher to build, and you maintain a front end permanently | In between, with fewer novel problems |
| How it typically fails | Plugin sprawl and a theme nobody can safely update | A content model shaped like pages, and no preview | Being sold as headless when it is not, and disappointing both camps |
The short version
If you have one website, one team, no second channel on the roadmap, and your real complaint is that the site looks dated, headless is an expensive answer to a question you have not asked.
We say this on a page selling headless development because the alternative is worse: taking on a project we know will hand a small team an architecture they cannot operate, and being the agency they resent in eighteen months.
The honest test is whether content genuinely needs to exist independently of pages. If it does, the cost is justified and the benefit compounds. If it does not, a modern traditional platform will do everything you need and let you spend the difference on the work that actually moves the business.
What goes wrong
The four ways headless projects disappoint
- The content model is a set of page templates.
- Someone models a "homepage" type, an "about page" type and a "landing page" type, each with fields for the sections that appear on it. That is a page-based system with extra steps: nothing can be reused, and the reason for choosing the architecture has been designed out of it on day one.
- Preview never arrived.
- It was on the list, it slipped, and editors now publish and check afterwards. Within a month someone is drafting in a document and pasting in at the last minute, which is the point at which the workflow you paid for stops existing.
- Nobody owns the search plumbing.
- Redirects have no home, the sitemap is generated once and never again, canonical tags are hard-coded, pagination returns a status code nobody checked, and removed pages return a page saying not found while reporting that everything is fine.
- The front end has one maintainer.
- A build that only its author can deploy is a risk regardless of how good it is. Headless increases the amount of custom code you own, so the question of who else can run it needs answering before the contract is signed rather than after they leave.
Scope
What a headless build has to include to be finished
This is the list that separates a project that works from one that technically launched. Most of it is invisible to whoever signed the budget.
- A content model built from real things — people, products, locations, policies — rather than from page layouts
- Roles, permissions and an approval flow that match how the team actually publishes
- Working preview for drafts and for scheduled content, available to editors without a developer
- Server-side rendering for every page that has to be indexed, verified by inspecting rendered output
- A routing and redirect system with an interface, so redirects are not a deployment
- Automatically generated sitemaps that reflect what is actually published today
- Correct status codes for removed, moved and missing pages, tested rather than assumed
- Metadata and canonical logic owned in code, with editors able to override where it matters
- An image pipeline handling sizing, formats and lazy loading centrally
- Localisation structure if more than one language will ever exist, decided before launch
- Content migration including archives, redirects from old addresses, and the things nobody wants to inherit
- Documentation and a second person who can deploy the front end
How we run it
Decide first, build second
Establish whether you need it
Channels today and on the roadmap, size and shape of the editorial team, publishing frequency, the capability you have in-house, and what is genuinely wrong with the current setup. This step ends in a recommendation either way.
You get: A written architecture recommendation with the case against
Model the content with the people who write it
Workshops with editors, not only with developers. Model the things the business talks about, test the model against awkward real examples, and check that no fact needs maintaining twice.
You get: A content model and editorial workflow specification
Assign the responsibilities the platform used to hold
Routing, redirects, canonical tags, sitemaps, status codes, pagination, search, media. Each gets an owner and an implementation plan before front-end work begins.
You get: A responsibility matrix covering every platform behaviour
Build front end and editorial experience together
Preview, drafts and scheduling are built alongside the public pages rather than after them, because the team that has to use the system daily is the one most likely to abandon it.
You get: A working front end with preview from the first release
Migrate and launch as a migration
A replatform moves addresses, so it is treated with migration discipline: inventory, redirect map, benchmark, staged release and monitoring.
You get: Migrated content with redirects and a post-launch report
Hand over properly
Training for editors, documentation for developers, and a deliberate second person who can deploy. A system only one person can operate is not finished.
You get: Training, documentation and a verified second deployer
Questions
What teams ask before committing to this
Is a headless CMS better for SEO?
Not inherently. It is neutral, and it can be worse if the front end renders content only in the browser or if nobody is made responsible for redirects, canonical tags and sitemaps.
A well-built decoupled site and a well-built traditional site are both fine. The difference is that the traditional platform gives you a lot of that behaviour by default, and the decoupled one gives you a blank page and a deadline.
When is headless clearly the right choice?
When the same content genuinely has to appear in more than one place — a website, a mobile application, in-store screens, a partner feed — and maintaining it separately in each is already causing errors.
It is also a reasonable choice when several front ends share one editorial team, or when the publishing workflow itself has outgrown what a page-based system can express.
When would you tell us not to do it?
When there is one website, one small team, no second channel on the roadmap, and the current frustration is design rather than architecture. In that situation a modern traditional CMS does everything needed and keeps preview, editing and publishing simple.
We would also advise against it when nobody internally can deploy a front end. Choosing an architecture that requires a capability you do not have creates a dependency rather than a solution.
What happens to preview?
It has to be built. Editors need to see a draft as it will appear, including scheduled and unpublished content, and that requires a preview route in the front end that reads draft data safely.
We treat it as a launch requirement rather than a later enhancement. Teams that publish daily will abandon a system that makes them guess.
How do you model content properly?
By modelling the things themselves — a person, a product, a location, a policy, an event — rather than the pages they appear on. A page then becomes an arrangement of those things.
The test is simple. If a fact has to be edited in two places when it changes, the model is describing pages instead of describing the business.
Get an architecture recommendation you can show your board
Tell us how many channels you publish to, how many people edit, and what is actually going wrong today. We will tell you whether this architecture is worth its cost for you, in writing, including if the answer is no.
Related
Where to go next
- replatforming an established siteMost headless projects are also migrations, with all the risk that carries.
- crawling, rendering and indexingThe responsibilities a decoupled build hands to your developers.
- headless on a commerce platformWhere the storefront is decoupled but the commerce engine is not.
- search work at organisational scale
- work with technology companies
- what a build of this kind costs
Last updated · Reviewed by Zubair Afzal