Headless CMS or not: a decision framework instead of a trend

Headless CMS architecture got popular fast, and like most fast-popularizing patterns, it started getting recommended for projects it doesn't actually suit. A headless setup, where your content lives in a CMS entirely decoupled from how it's rendered, is a genuine architectural upgrade for the right project and unnecessary complexity for the wrong one.

If the same content needs to power multiple front ends, a website, a mobile app, a partner integration, headless architecture avoids duplicating that content across systems. It also decouples your content editing experience from your rendering framework, which matters if you expect to redesign or rebuild the front end without re-migrating all your content, a real cost with traditional coupled CMS platforms like a standard WordPress theme.

A single marketing site with no plans for a companion app or multi-channel content reuse usually doesn't need the extra moving parts. Headless setups require you to build and maintain the front end entirely yourself (there's no built-in theme system), which is more initial engineering work for a benefit, decoupling, that a simple single-site project may never actually use.

Traditional CMS platforms like WordPress give non-technical editors a visual, in-context editing experience, what you see roughly resembles the live page. Headless CMS editing is usually more form-based, filling in structured fields rather than editing visually in place. For content teams used to visual editing, this can be a real adjustment, and it's worth letting the actual content editors try the headless CMS's editing interface before committing, not just evaluating it from an engineering perspective.

We recommend headless when at least two of these are true: the content needs to power more than one front end, the team expects to rebuild the front end within two to three years, or there's a specific performance requirement that a headless static-generation approach solves better than a traditional CMS. Fewer than two, and a traditional coupled CMS is usually the faster, cheaper, equally correct choice.

Headless projects typically cost more to build initially, since there's no theme ecosystem to lean on and the front end is fully custom. Clients considering headless purely because it's the newer-sounding option should know that upfront cost difference before it becomes a surprise partway through a proposal review.

A traditional coupled CMS locks you into its own rendering and templating system, while a headless CMS locks you into its content modeling and API, a different kind of lock-in, not an absence of one. Before committing to a specific headless provider, we check what a future migration away from it would actually require: can content be exported cleanly in a standard format, or is it modeled in ways specific to that vendor that would need significant rework to move elsewhere.

This matters more for headless setups than people initially assume, since the appeal of headless is often framed as flexibility, and that flexibility is only real if the content itself isn't tightly coupled to one vendor's specific modeling conventions. We favor headless CMS platforms with straightforward content export options for exactly this reason, even when a more tightly integrated competitor offers a marginally smoother initial setup experience.

Several modern CMS platforms now offer both a built-in front end and headless API access from the same content model, letting a team start with the simpler coupled approach and adopt headless patterns incrementally for specific sections as the need arises, rather than committing fully to one architecture from day one. For teams genuinely uncertain which path they'll need in two years, this middle option is worth evaluating before committing to either extreme.

A regional fitness brand came to us needing the same class schedule and instructor bios to appear on their marketing site, inside their member mobile app, and syndicated to two partner gym directories. That's close to the textbook case for headless: one content source, several genuinely different consumers of it, each with its own rendering requirements the others couldn't share.

We built the content model in a headless CMS with the marketing team entering schedule and instructor data once, and each of the three destinations pulling from the same API on its own release cycle. Before this, the same schedule was being manually re-entered in three separate places, and updates regularly went stale in at least one of them within a week. That specific, recurring pain, not a general preference for newer architecture, is what actually justified the added engineering complexity.

A common assumption is that headless automatically means faster, since the front end is fully custom rather than running on a general-purpose CMS theme. That's only true if the custom front end is actually built well. We've seen headless sites with worse Core Web Vitals scores than a well-optimized traditional CMS site, because the flexibility of a custom front end also means there's no theme-level guardrail preventing an unoptimized build.

Headless architecture removes a ceiling on performance, it doesn't guarantee a floor. The performance outcome still depends entirely on how carefully the front end consuming the API is actually engineered, which is worth stating clearly to any client choosing headless primarily for a speed benefit they assume comes automatically with the architecture.

We push for both the content team and the engineering team to be in the room for this decision, not just engineering leadership. A headless CMS's form-based editing experience can be a genuine productivity loss for a content team used to visual editing, and that's a real cost that engineering alone won't necessarily weigh correctly, since they're not the ones publishing content day to day. We've seen technically sound headless recommendations get quietly resented and worked around by content teams for months after launch, purely because the people who'd actually use the editing interface daily weren't part of the original decision.