What is Headless CMS?
A content management system that stores structured content and delivers it through APIs, leaving presentation entirely to separate frontends.
Definition
A traditional CMS such as classic WordPress or Drupal owns both the content database and the HTML templates that render it. A headless CMS keeps only the first half: editors author structured content in an admin interface, and the CMS exposes that content as JSON through a REST or GraphQL API. Any client can consume it, whether a Next.js or Astro website, a native mobile app, an email builder, or a digital sign. The "head" (presentation layer) is something the development team builds and deploys separately. Content is modeled as typed entries with fields and references (an Article with a title, rich-text body, author reference, and SEO fields) rather than as pages. Hosted SaaS options include Contentful, Sanity, Storyblok, and Hygraph; open-source, self-hostable options include Strapi, Payload, Directus, and Decap CMS (Git-based). WordPress and Drupal can also run headless through their REST APIs or plugins like WPGraphQL. Publishing typically fires a webhook that triggers a static rebuild or on-demand revalidation of only the affected pages, and preview modes let editors see drafts rendered by the real frontend. The benefit is separation: content is reusable across channels, frontend teams pick their own framework, and the public site can be served statically from a CDN with the CMS off the request path. The cost is that features a monolithic CMS gives for free, such as page previews, menus, URL routing, and visual page building, must be built or configured on the frontend.
When to Use Headless CMS
Choose a headless CMS when the same content feeds several channels, when developers want full control of the frontend stack, or when you want a statically generated or edge-rendered site for performance and security. It also suits teams adding editor-managed content to an existing app. Stay with a traditional or hybrid CMS if marketers need drag-and-drop page building without developer help, or if there is no frontend team to maintain the presentation layer. Compare pricing models carefully: SaaS plans often meter API calls, seats, and locales. Self-hosted options remove those limits but add hosting, backups, and upgrades. Invest in the content model up front; it is the hardest part to change later.
Headless CMS in Practice
- Fetching published articles from a headless CMS's GraphQL API at build time in a static site: const res = await fetch(CMS_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${TOKEN}` }, body: JSON.stringify({ query: '{ articles { slug title publishedAt } }' }), });
- A publish webhook calls a Next.js route that runs revalidatePath('/blog/' + slug), so only the edited post is regenerated instead of rebuilding the whole site.
- A retailer keeps product stories in Sanity and renders the same entries on its Astro website, in its React Native app, and in promotional emails.
- A startup self-hosts Strapi in Docker next to Postgres to avoid per-seat SaaS pricing, accepting responsibility for upgrades and backups.
Common Mistakes
- Modeling content as page layouts (hero block, three-column block) instead of meaningful types. This ties content to one design and defeats reuse; model the domain first.
- Forgetting editor preview. Without a draft-mode integration, editors publish blind; set up preview routes using the CMS's draft API.
- Querying the CMS API on every page request from the browser, exposing tokens and hitting rate limits. Fetch at build time or on the server and cache.
- Rebuilding the entire site on every publish as content grows. Use incremental or on-demand revalidation triggered by webhooks.
- Ignoring SEO fields, redirects, and sitemaps, which a monolithic CMS often handled automatically. Add them to the content model and frontend.