Headless website development, and knowing when not to do it
Headless is a trade rather than an upgrade. It moves work from the server to a build pipeline and from the theme to an API, and whether that is a good trade depends on what you are delivering and who has to edit it. The first thing we do is establish which side of that line you are on.
Headless is usually chosen for a reason that does not require it
Decoupling a CMS from its front end solves real problems: delivering one body of content to several surfaces, giving a front-end team framework freedom, or serving content into an application. It also introduces real costs: a build pipeline that can fail, a preview workflow that has to be built rather than inherited, editorial tooling that no longer comes with the CMS, and a delivery path with more places for a rendering problem to hide. When it is chosen because it sounds more modern, the organisation pays the costs and receives none of the benefits.
- Content has to serve several front ends: web, application, kiosk or partner surfaces
- The front end needs a framework the CMS cannot reasonably render
- Editorial and presentation concerns have genuinely separated
- A monolith's release process is the constraint rather than its features
- Performance is the stated motivation and has not been tested against the alternative
- Nobody has decided who owns the build pipeline in production
- Content preview has not been discussed at all
- The team responsible for the front end is different from the team responsible for the CMS
The people who usually bring us this problem
CTO / VP Engineering considering decoupling
You have a case for it and you need the trade-offs stated by someone who is not selling the architecture.
A product team delivering to several surfaces
One body of content genuinely has to reach more than one place, and the current arrangement cannot do it without duplication.
A team whose editorial workflow is the constraint
Publishing is blocked by the release process rather than by the platform, and you need to know whether decoupling is the right answer to that or an expensive detour.
What this costs while it goes unfixed
Engineering faults are rarely confined to the engineering layer. These are the commercial consequences we see most often.
The build pipeline becomes production infrastructure
In a decoupled architecture, publishing runs through a build. A pipeline that fails, or that nobody owns, is not an inconvenience — it is the publishing system being down. That ownership has to be assigned before the architecture is chosen, not after it fails.
Editorial tooling is now something you build
A coupled CMS ships preview, scheduling and media handling as part of the product. Decoupled, each of them is either rebuilt or lost. Losing preview is a change in how editors work that is rarely priced into the decision.
Performance can get worse, not better
Headless removes server-side rendering from the origin, which can be a large win, and adds a client-side rendering path, a data-fetching layer and a build step — each of which can be a loss. The net result is an architecture question that is answerable by measurement and not by assumption.
There are more places for a fault to hide
A rendering problem in a coupled stack is in one application. Decoupled, it could be the API, the build, the cache, the front end or the contract between them — which makes diagnosis slower and raises the value of instrumenting the path before you need it.
Capabilities
Each of these is work we carry out, not an area we advise on.
Architecture assessment and honest recommendation
Establishing whether decoupling solves a problem you actually have, and saying so if it does not. This is the first deliverable and it is not always an architecture proposal — sometimes it is a recommendation to fix the existing stack's release process instead.
Content model and API design
The contract between the CMS and the front end treated as a designed interface: what is exposed, in what shape, versioned how, and how a change to content structure propagates without breaking a deployed front end.
Front-end engineering
Building the delivery layer with attention to what a decoupled stack makes easy to get wrong — render strategy per route, data fetching, caching, hydration cost and the boundary between what is built and what is fetched.
Editorial workflow and preview
Reconstructing what a coupled CMS provided for free: preview of unpublished content, scheduled publishing, and a route from editorial change to a seeable result. Usually the most under-scoped part of a headless project and the part editors experience most directly.
Build pipeline and release engineering
The pipeline as production infrastructure: what triggers a build, how a failure is detected and handled, who owns it, and how a publish gets out when the build is unavailable.
Search-visible delivery
Server-rendered or pre-rendered output where it is needed, correct canonicals and structured data, and a sitemap generated from the same source of truth as the pages. Headless does not make this harder inherently, but it does make it easier to get wrong invisibly.
Performance measurement rather than assumption
Core Web Vitals measured on the decoupled stack and compared against the coupled alternative, because the architecture does not determine the outcome. Where the numbers do not support the change, we will report that.
Content migration and redirects
Where an existing site is being re-fronted, existing URLs and their search visibility are part of the scope, including the structured-data and canonical decisions that determine whether the new front end is found.
Operational handover
Documentation of the pipeline, the API contract, the caching strategy and the failure modes, so the architecture can be operated by the team that owns it rather than by whoever designed it.
Engineering methodology
The sequence is deliberate. The order is usually what determines whether the work holds or has to be repeated.
Establish the problem before the architecture
What is actually blocking you: multiple delivery surfaces, a release process, framework constraints, or a preference. Only some of those are solved by decoupling, and the assessment says which — including when the answer is that a coupled stack with a better release process would be cheaper.
Cost the parts that do not come free
Preview, scheduling, media handling, sitemap generation and search. In a coupled CMS these are provided; decoupled they are built or lost. Deciding that explicitly, before committing, is what stops a headless project delivering a front end and quietly removing the editorial workflow.
Design the API contract as an interface
What is exposed and in what shape, with versioning and a stated policy for change. A content API that mirrors the CMS's internal structure rather than the needs of its consumers is the most common way a decoupled stack becomes as coupled as the thing it replaced.
Choose render strategy per route, not per site
Static generation, server rendering and client rendering are decisions that can differ across a site, and the right answer is usually a mixture. Applying one strategy to everything is simpler to describe and worse in operation.
Instrument the delivery path
The path from request to rendered page crosses more boundaries in a decoupled stack, so it is instrumented before it is needed rather than after the first fault. Diagnosing a decoupled rendering problem without telemetry is substantially harder than diagnosing a coupled one.
Measure, then state the outcome
Performance and search metrics are compared against the previous architecture or a representative alternative. If the decoupled build does not improve what it was chosen to improve, that is the finding, and it is reported as one.
What an engagement produces
Documentation is a deliverable, not an afterthought. On most of these engagements a large part of the value is a defect report precise enough for another team to act on.
Assessment
- Statement of the problem the architecture is meant to solve
- Whether decoupling solves it, with the reasoning stated either way
- What has to be rebuilt that the CMS currently provides
- Comparison of delivery performance against the alternative
- Explicit statement of what the change will not improve
Build
- Content model and API contract with a versioning policy
- Front-end implementation with per-route render strategy
- Editorial preview and publishing workflow
- Sitemap, canonicals and structured data from a single source of truth
- Caching and invalidation strategy across the delivery path
- Build pipeline with failure detection and an owner
Handover
- Documentation of the pipeline, API contract and caching model
- Runbook for the failure modes that actually occur
- Monitoring of the delivery path and the build
- Stated position on who owns the pipeline after launch
- Content and redirect migration where a previous site existed
Architecture and technology
The trade, stated plainly
- Gained: one content source serving several front ends
- Gained: front-end framework freedom
- Gained: content delivery independent of the CMS's render path
- Lost: preview, scheduling and media handling that a coupled CMS provides
- Lost: a rendering fault having one place to be
- Lost: publishing that does not depend on a build pipeline running
What has to be decided before committing
- Who owns the build pipeline in production, and what happens when it fails
- How unpublished content is previewed by editors
- Which routes are static, server-rendered or client-rendered, and why
- How the API contract changes without breaking a deployed front end
- How canonical URLs, sitemaps and structured data stay single-sourced
- How a rendering fault is diagnosed across the extra boundaries
If this is not quite your problem
These overlap at the edges. Sending you to the right page is more useful than having you work it out.
The motivation is performance rather than delivery surfaces
Measure first; the architecture does not determine the outcome.
Website performance engineeringThe motivation is how content is authored
Content modelling in a coupled CMS solves more of this than decoupling does.
WordPress developmentClient-rendered content is not being indexed
Making a rendered front end crawlable is a distinct problem from building one.
JavaScript SEOThe CMS is staying and only the delivery is changing
Keeping the content source and replacing the front end is often the lower-risk version.
WordPress developmentFrequently asked
Will headless improve our Core Web Vitals?
Not automatically, and treating it as an assumed benefit is the most common mistake we are asked to review. Decoupling removes server-side rendering cost from the origin, which can help substantially, and it adds a build step, a data-fetching layer and a client-side render path, any of which can cost more than was saved. The net effect is an architecture question answerable by measurement. If your motivation for headless is primarily performance, measure the current stack's actual bottleneck first — it is frequently a smaller and cheaper fix.
What happens to content preview for our editors?
It has to be built, because a coupled CMS provides it and a decoupled one does not. This is the part of headless projects most often under-scoped and most directly felt by the people using the system daily. We treat preview and scheduled publishing as required deliverables rather than optional, and cost them at the assessment stage so the decision is made with the full picture.
Who owns the build pipeline after launch?
It has to be a named party before the architecture is chosen, because in a decoupled stack the pipeline is production infrastructure — publishing runs through it, and if it fails, publishing stops. Some clients take it in-house and we hand over documented; others keep it with us. What we will not do is deliver a decoupled site with no answer to this, because that is how a content operation ends up dependent on a background process nobody watches.
Can we keep our current CMS and only replace the front end?
Often yes, and it is frequently the lower-risk version of this work. Keeping an established content source and replacing only the delivery layer limits what has to be rebuilt editorially and leaves the content ownership where it already sits. Whether it is the right answer depends on whether the CMS can expose what the new front end needs, which is established in the assessment rather than assumed.
Is headless better for SEO?
No — it is neutral, and it makes some SEO mistakes easier to make invisibly. A decoupled front end can produce exactly the same crawlable HTML as a coupled one, and often does. What changes is that rendering happens further from the content, so a front end that renders client-side without a pre-render path, or that generates canonicals inconsistently, degrades search visibility without any obvious symptom in the editor. Handled deliberately it is fine; assumed to be fine it is a risk.
Related capabilities and work
Bring us the problem you have not been able to fix
Describe what is happening rather than what you think the cause is. If we are not the right people for it, we will say so.