What Is a Headless CMS? My Experience Building and Rescuing Sanity Projects

A client was paying for a Sanity subscription for months. Nobody had ever connected it to their website. Every headline, team bio and article was a hardcoded string inside a JSX component. The CMS sat billed and unused while the site produced zero search traffic and zero content updates.

That situation taught me more about headless CMS than any documentation page. I have built on Sanity and I have rescued projects that were supposed to run on it. This post is what I wish someone had handed me the first time I had to explain the concept to a business owner. This blog itself runs on a headless CMS. The client sites I build run on Sanity, so these are opinions earned in production.

If you are a developer evaluating Sanity, or a founder whose developer keeps saying the word "headless", this will save you the expensive version of the lesson.

---

The Client Who Paid for a CMS Nobody Connected

I took over a project from a team that had burned through two developers. The site looked finished: clean layout, smooth animations, all the right pages. Under the hood it was a different story.

• A Sanity subscription had been billing for months with zero content connected. Every piece of text lived as a string inside a JSX component.
• The site rendered entirely client-side. Googlebot received blank HTML shells, so the site had been live for months with nothing for a search engine to index.
• Editors could not change a single word. The client had a CMS license, a login and no way to use either.

I wrote the full story in I Took Over a Project After a Vibe Coder. The short version: the project failed because nobody understood what the CMS was for. Which brings me to the actual question.

What a Headless CMS Actually Is

A headless CMS is a content management system without the "head": the part that renders pages. A traditional CMS like WordPress is one package: database, admin panel, templates and the code that turns content into HTML, all in one place. Content and presentation are welded together.

A headless CMS splits that in two:

• The content side: the database, the admin interface and the API that serves content. Editors write and structure content here.
• The presentation side: your website, app or any other frontend. It pulls content from the API and renders it however it wants.

Think of the CMS as a kitchen. A traditional CMS is a restaurant where the kitchen and the dining room share a wall. Every table is served from that one kitchen. A headless CMS is a kitchen that sends every dish through a hatch: any dining room can pick the food up. The kitchen does not care which one you choose, or whether you open three dining rooms at once.

The word "headless" means the content backend does not care what your frontend looks like. The same content can feed a Next.js site, a mobile app, a landing page and increasingly an AI agent, without duplicating anything.

For a frontend developer this is a natural fit. I spend my working life in React and Next.js, so the idea that my UI is one consumer of content feels obvious. For a business owner it is the opposite of obvious. That gap is where projects like my client's go to die.

Why Sanity Feels Different

Sanity is one of the more popular headless options. It is the one I reach for on client projects. The reasons are real. They are not the ones on the marketing page.

The content model is code. In Sanity you define content types, called schemas, in JavaScript or TypeScript. A blog post, a team member, a product: each one is a schema with typed fields. This is the feature I value most. The schema lives in your repository, it goes through code review and it changes the same way your code changes. Sanity's docs on schemas show the pattern: define types, add fields and the Studio generates the editing forms from that definition.

Queries are explicit. Sanity ships its own query language, GROQ. You write the exact shape of data you want and you get that shape back. Nothing extra, nothing missing. On the rescue project, replacing hardcoded strings with GROQ queries was the mechanical part of the work. It took days, not weeks.

Rich text is structured data. Sanity's Portable Text stores rich text as JSON blocks instead of HTML. It sounds like an implementation detail, but it changes what editors can do: the same article body can render as a webpage, as an app screen or as clean text for a screen reader. You keep full control of the markup. That last point matters to me because I run accessibility audits. Hardcoded, nested, inaccessible HTML is exactly the kind of thing structured content prevents by design.

No frontend lock-in. Sanity works with any framework. I use it with Next.js, but the API does not care. You can switch your frontend without touching your content, which is the entire point of decoupling.

Real-time collaboration. The Studio supports live editing. It sounds like a nice-to-have until two people are editing the same page. For content teams it removes a whole class of "who saved last" conflicts.

Where Headless Bites Back

I will not sell you headless as the answer to everything, because it is not. The tradeoffs are real. A senior developer should say so out loud.

Editors lose the page preview. In WordPress, what you see in the admin is roughly what visitors get. With headless, the CMS shows structured fields. The final page exists only after your frontend renders it. You can build preview environments and you should, but that is engineering work you are now responsible for.

Every change to the content model needs a developer. Adding a field, changing a validation rule, restructuring a content type: that is a code change. For a small business with no developer on staff, the "no developer needed" promise of a traditional CMS is operational reality, not just comfort.

You own more of the pipeline. A traditional CMS hosts and renders for you. With headless you are responsible for the frontend host, the build, the preview, the image optimization and the cache. I like owning that because it is the part I am good at. A business owner does not.

Headless is overkill for many sites. If you have a brochure site that changes twice a year, Sanity plus Next.js is a solution looking for a problem. WordPress, or a static site generator with a simple admin, will serve you better and cheaper.

The rule I apply: headless pays off when content changes often, when content feeds more than one channel, or when you need precise control over the rendered output. If none of those apply, you are paying for architecture you will never use.

What I Tell Business Owners

After the rescue, I sat down with the client and explained what happened, because the same conversation comes up on every project.

A CMS and its integration are one purchase. When you pay for Sanity, you get a database and an editor. The website is the integration: the schemas, the queries, the rendering. Skip the integration and the invoice keeps arriving while the site stays empty.

Judge any CMS by the first edit. The demo shows you what the vendor wants you to see. The first edit shows you what your team will live with: can they change a headline today, without emailing a developer? If the answer needs a code deployment, the CMS is decorative.

Hardcoded content is a business risk. Content trapped in components cannot be indexed properly, cannot be updated by your team and cannot be reused. On the rescue project, the blank HTML shells meant months of zero organic traffic. The numbers on vibe-coded failures match what I found: the quiet failures, the CMS never integrated, the content never wired up, are the common ones.

Why Headless Matters for SEO and Speed

Since this post is about the practical case, the SEO angle deserves an explicit section.

Content in the HTML beats content in JavaScript. With a headless CMS and server-side rendering or static generation, your content sits in the raw HTML that Googlebot receives. That is the difference between the rescue site and the rebuilt version. The first sent search engines empty shells, the second sends them the actual articles.

Structured content is better for search. A schema defines fields for titles, descriptions, images and dates. That structure maps cleanly to metadata and gives you one canonical place for your SEO basics.

Performance is under your control. You choose the frontend, the rendering strategy and the image pipeline. On a fast, statically generated site, the CMS is rarely the bottleneck.

Conclusion

Headless CMS is a simple idea with a complicated set of consequences. Content lives apart from presentation, an API connects them and everything from your schema design to your preview setup determines whether the result is a working website or a monthly bill.

My experience across builds and rescues: headless is excellent when you have a developer who owns the integration and content that changes often. Sanity, specifically, is the option I would pick for that setup. It is expensive theater when you have neither. And if your team is already paying for a CMS nobody connected, the fix is usually integration work. A rebuild rarely enters the picture. That was true for my client. The rescue cost less than what they had already paid the previous developer.

If you want to see how I think through architecture decisions like this, including the tradeoffs and the mistakes, I run a community for developers and founders called The Agentic Architect Lab. We talk about building with AI, shipping products and the senior judgment that turns tools into working systems. Join the Lab here.

Sources

• Sanity: Headless CMS 101: https://www.sanity.io/headless-cms
• Sanity docs: Schemas and forms: https://www.sanity.io/docs/studio/schemas-and-forms
• Sanity docs: GROQ: https://www.sanity.io/docs/groq
• Sanity docs: Presenting Portable Text: https://www.sanity.io/docs/presenting-block-text
• Wikipedia: Headless content management system: https://en.wikipedia.org/wiki/Headless_content_management_system