Headless CMS

The name describes the removal of the “head”: the presentation layer that drew the pages, taken off the body that manages the content. What remains stores typed fields and serves them over REST or GraphQL, and a separate front-end application decides what a visitor sees. Drupal’s documentation calls the same arrangement decoupled, defining decoupled Drupal as separating the back end that manages content from the front end that presents it, and treating headless as another name for it.

That split determines how the site is built and maintained from then on. What follows covers the parts a buying team feels: how content reaches a visitor, what happens to the front end and to preview, what editors see when they open an entry, and the inventory of work that moves onto your team. For a head-to-head reading of the two models, see headless vs traditional CMS.

Delivery is an API call, and something else renders the result

A visitor’s request no longer terminates at the CMS. A front-end application receives it, calls the CMS over REST or GraphQL, gets typed fields back as JSON, and assembles the HTML the browser receives. The CMS’s job ends when it returns the data.

Because content arrives as fields, one entry can serve several destinations. A website, a native app, an in-store display and an email template each take the fields they need and arrange them their own way. How much of that reuse is genuinely available depends on how the content was modelled, which is the subject of structured content and content model. If the model was built around a single page layout, other channels receive that layout’s fields and little else.

Front ends commonly cache or pre-render pages, so publishing in the CMS and the change appearing to visitors become two separate events joined by a cache invalidation, usually triggered by a webhook. Editors notice this on day one. “I published it and it is not there yet” is a support question that a traditional CMS rarely produces.

The front end becomes a second application with its own build and deploy

The presentation layer is now a codebase your organisation owns, with dependencies, a build step, a deploy pipeline, environments, error monitoring and a framework upgrade path. Two systems now run in production, and a change can break in either.

Routing moves with it. In the Next.js App Router, folders define the route segments that map to URL segments and a folder name wrapped in square brackets creates a dynamic segment, so the URL structure of the site is defined in front-end code. Compare what a traditional CMS and its theme handle between them: WordPress matches a request against a template hierarchy and uses the first template file in it that matches, so search.php, archive.php, 404.php and the rest are supplied by the theme. Under headless, the equivalents exist in your front end and somebody writes them: the listing page, the detail page, the 404, the redirect table, the sitemap, the canonical tags.

A traditional theme supplies that work. Under headless it becomes ordinary engineering hours, and they do not appear on a licence quote. CMS TCO covers where they land in a budget.

Preview becomes an integration you build and keep working

In a traditional CMS, preview is the rendering engine reading an unpublished row. Once rendering lives in a separate application, a preview has to cross that boundary, and both sides document the same shape.

The CMS opens a URL on the front end carrying a shared secret and the path to preview. A route handler on the front end validates the secret, enables draft mode by setting a cookie that bypasses every cache layer, and redirects to the page, which then fetches draft content. Next.js documents this flow down to the name of the cookie, and notes that the handler is public to anyone who finds it until the secret check is added. Strapi documents the CMS half: a handler maps each content type to a front-end path and returns the draft or published URL, and its documentation states plainly that setting up the front-end preview route is highly dependent on the framework used. Embedding that preview inside the admin panel also requires the front end to allow being framed, through its CSP frame-ancestors directive.

Side-by-side preview asks for more. Payload renders the front end in an iframe inside the admin panel and emits window.postMessage events every time a change is made to the document; the front end has to listen for those events and re-render itself with the data it receives. Sanity’s visual editing asks the front end to configure its client to request content source maps and stega-encode the strings that come back, and to call enableVisualEditing() when draft mode is active, so that clicking rendered text sends the document id and field path to the Studio, which opens the field.

The flows are well documented, and they are also ongoing. Every new route, and every component that composes fields in a new way, has to keep the preview contract intact, so preview belongs in the maintenance line as well as the build estimate.

Editors see fields, and the page view is something you decide to build

An editing screen in a headless CMS shows an entry’s typed fields. Teams that ship without the preview integration ask editors to hold the layout in their heads, and the cost shows up as extra review rounds and a habit of checking everything on staging before publishing.

On rich, layout-heavy pages, a field-based editor offers typed blocks drawn from a defined set. Content stays portable, and an editor cannot invent a one-off arrangement. Marketing teams accustomed to dragging a hero, a two-column band and a testimonial onto a page will ask for that capability back, and the answer is a block library someone designs, builds and documents. Editorial control that used to be enforced by the platform now has to be expressed in the model and in code, which is the subject of content governance in a headless CMS.

What the CMS provides and what your team provides

Vendor documentation covers the left column; the right column is the part a buying team has to size for itself.

Capability	What a headless CMS typically provides	What your team provides
Content modelling	Field types, relationships, validation, localisation, drafts and versions	The model itself: which types exist, what fields they carry, how they relate, and the discipline to keep it coherent
Editing interface	Forms generated from the model, roles and permissions, media library	Any affordance beyond fields: a block library, layout composition, in-context editing
Content delivery	REST and GraphQL endpoints, filtering, pagination, API tokens	The queries, the caching strategy, and the invalidation that makes a publish visible
Front end	Nothing	The whole application: components, design system, accessibility, performance budget, build and deploy pipeline, framework upgrades
Routing and URLs	A slug field	Route definitions, listing and detail pages, pagination, 404s, the redirect table, canonical tags, sitemap and robots
Preview	A preview URL setting and a draft API or token	The preview endpoint, secret handling, cache bypass, draft fetching, the editor banner, and the CSP allowance for framing
Site search	Filtered queries over its own content, sometimes basic full-text	The search experience: indexing, ranking, typo tolerance, facets, the results page. Often a separate search service and its subscription
Forms	A form’s fields modelled as content	Rendering, client and server validation, spam handling, submission storage, notifications, and the CRM or marketing integration
Media	Upload, storage, usually derivative sizes and a CDN	Which formats and sizes each surface requests, art direction, alt-text practice, and the loading strategy on the page
Hosting and operations	The CMS itself, when bought as SaaS	Hosting, CDN, TLS, environment configuration and monitoring for the front end. Under self-hosting, the same again for the CMS
Personalisation, testing, analytics, consent	Usually nothing	Every one of them, chosen and integrated separately

Several of these lines arrive after launch as ordinary engineering work, so a feature-by-feature comparison of two products will not show them. Assembling capabilities this way is the trade described under composable architecture, and the running cost of it belongs in CMS TCO alongside the licence.

Where headless is the wrong answer

• One website, one destination, no second channel on the roadmap. The platform already routes the request, and a theme supplies the search results page and the 404 page; plugins cover forms. Headless converts each of those into a build item, and the content reuse that pays for the split needs a second destination to exist.
• No standing budget for the front end. A headless setup assumes an application that receives dependency updates, framework upgrades and small fixes for as long as the site is live. Teams that treated the CMS purchase as the end of the spend discover the front end has a maintenance line of its own.
• Editors whose main job is composing one-off pages, when nobody has scoped a block library or in-context editing. Either can be built, once it is scoped and funded.
• Short-lived campaign and event sites. The work of standing up a second application rarely returns within the life of the site.
• Plugins currently doing real work. Memberships, e-commerce, event registration, gated downloads, a mature forms-and-spam stack. Each becomes a service to buy or code to write.
• A hybrid arrangement already covers the requirement. WordPress ships a REST API in core that sends and receives content as JSON, and Drupal documents decoupled use directly, so a team can feed an app or a second surface while the main site keeps its rendered pages.
• The stated reason is that the current system feels dated. The requirement has not been written down yet. Write it down before comparing products. Five signs you’ve outgrown your CMS covers the symptoms that do justify a move.

What the word “headless” leaves undefined

Headless describes one axis: where rendering happens. Several things the label gets read as implying are left open by it. Where the software runs is a separate question, covered under self-hosted vs SaaS. Pricing model, the quality of the editing interface, and how readily your content and configuration could be lifted out are all specific to the product; the last of those is vendor lock-in. Headless products differ widely on every one of those points, so an evaluation has to be of the specific product.

A headless CMS is often the content-management part of a wider content platform, and it is one of the four ideas in MACH. The suite model it is usually weighed against is the DXP. Moving between two headless systems is a project in its own right, with the same shape as any other replatforming, and a pre-migration checklist for non-technical teams covers what to establish before a decision is made.