Headless CMS became the default recommendation in agency pitches around 2020. Four years later, a more nuanced picture has emerged: headless architecture solves real problems for specific project types, and adds significant complexity for others. Here is an honest framework for making the decision.

1. Traditional vs Headless vs Decoupled

These three terms are often conflated. They represent a spectrum:

  • Traditional (coupled): CMS handles both content management and rendering. Drupal with Twig themes, WordPress with PHP templates. One system, one deployment, one team.
  • Progressively decoupled: CMS renders the page shell. React/Vue "islands" handle specific interactive components. Both teams share the same deployment but work on different layers.
  • Fully headless: CMS is a pure JSON API backend. A separate frontend application (Next.js, Nuxt, Astro) handles all rendering. Two systems, two deployments, two teams, two hosting bills.

2. When Headless Wins

Headless architecture delivers clear, measurable advantages in these scenarios:

  • Multiple frontends from one backend: Web app, native iOS, native Android, kiosks, and digital signage all consuming the same content API. This is the original use case and headless is definitively better here.
  • CDN-edge rendering at global scale: Next.js with ISR or Astro with static output, deployed to Cloudflare Pages or Vercel edge network, delivers sub-50ms TTFB globally. No traditional CMS can match this without significant caching infrastructure.
  • Frontend team with strong React/Vue preference: When the frontend team's expertise is in modern JavaScript frameworks and they find PHP templating limiting, headless lets each team work in their best tool.

3. When Headless Loses

These are the situations where headless adds cost without adding value:

  • Content preview is critical: Editors clicking "Preview" and seeing their draft in the actual frontend requires significant engineering โ€” Next.js Draft Mode, authentication tokens, environment coordination. In a coupled CMS, preview is a single button.
  • Small team, limited budget: Two deployment pipelines, two monitoring setups, CORS configuration, authentication, and preview complexity add up to 30โ€“40% more development time on typical projects.
  • SEO-critical content with frequent updates: Cache invalidation in headless setups (particularly ISR) has edge cases that can leave stale content live longer than expected.

4. API-First vs API-Also

There is an important distinction between CMS platforms that are "API-first" (built around the API, UI is secondary) and "API-also" (traditional CMS that also exposes an API). Contentful and Sanity are API-first. Drupal and WordPress are API-also. For pure headless use cases, API-first platforms have better DX. For hybrid or progressively decoupled, API-also platforms have much better editorial experiences.

5. Real Cost Analysis

On a typical 12-week project, headless adds approximately:

  • 2 weeks: frontend deployment setup, CI/CD for two pipelines, environment coordination
  • 1 week: authentication implementation (OAuth2 or API keys)
  • 1.5 weeks: content preview implementation
  • 0.5 weeks: CORS and environment variable configuration

That's roughly 5 weeks of overhead โ€” worth it for the right project, significant waste for the wrong one.

6. The Pragmatic Middle Ground

For most projects, the progressively decoupled approach delivers the best outcome: Drupal or WordPress handles routing, SEO, and content rendering. React handles specific interactive components (search, personalisation, live data). You get 80% of the benefits of headless at 20% of the complexity.