Why Sanity page builders keep failing and how to fix it

Sanity’s flexibility powers countless marketing sites, but its page builder implementations share a costly flaw. Whether you’re a developer or a team lead, you’ve likely encountered it: a new section added to the schema fails to render in production, leaving a blank space where content should appear. The issue isn’t the concept—it’s the repetitive, error-prone workflow that forces you to touch five different places just to add a single section.

The root of the problem isn’t complexity; it’s duplication. Every project reinvents the same plumbing while customizing only the visual components. This leads to subtle inconsistencies that slip past local testing but surface in live environments. The result? Hours lost debugging sections that technically compile but refuse to display.

The hidden cost of "adding a section"

When you expand a Sanity-based page builder with a new section, the process often involves five distinct steps:

• Registering a new schema type (e.g., heroSection) in your global schema index.
• Updating the GROQ query to include the new block’s fields, ensuring they’re fetched during rendering.
• Creating a React component tailored to your design system, brand tokens, and layout requirements.

• Mapping the block’s _type to its corresponding renderer in a dispatch function.

• Extending your TypeScript union to include the new section variant, keeping interfaces and types in sync.

Any omission in these steps—especially in non-visible areas like GROQ projections or renderer maps—results in silent failures. A missing field in the query might return an empty object; a skipped renderer map entry might silently ignore the block. The worst part? These issues often pass local tests only to fail in production, where real content and user traffic expose the gaps.

The core problem: plumbing duplicated across projects

The component is the only part that truly belongs in your repository—it’s tightly coupled to your design language, spacing rules, and visual identity. Everything else—the schema registration, the GROQ projection, the renderer map, and the type union—is infrastructure. It’s the same logic repeated in every project, rewritten from scratch each time.

This repetition isn’t just inefficient; it’s risky. Each rewrite introduces opportunities for drift. A schema type gets renamed, but the GROQ query isn’t updated. A new section is added to the union, but its renderer isn’t mapped. The TypeScript compiler may catch some issues, but not all—especially those tied to runtime queries or unvalidated schema strings.

A pattern to eliminate drift and reduce errors

The solution isn’t to avoid page builders altogether—it’s to extract the repetitive plumbing into a shared system. By co-locating the schema, query, and renderer in a single declaration, you prevent drift before it starts. This pattern can be implemented with lightweight utilities or standalone packages, but the underlying idea remains the same.

Consider a factory function that defines a section with all three critical elements in one place:

const defineSection = createSectionFactory<PageBuilderBlock, RenderContext, ReactNode>()

const hero = defineSection({
  type: 'heroSection',
  query: `title, subtitle, ctaHref`,
  render: (block) => <Hero {...block} />,
})

Here, the type, query, and render function are declared together, ensuring they stay in sync. No more editing multiple files and hoping nothing breaks. The same logic can generate both the GROQ projection and the renderer map automatically, eliminating manual synchronization.

Derive queries and renderers from a single source

With sections defined as structured objects, you can build a page builder that generates both the query and the dispatcher from the same list. This approach turns implicit dependencies into explicit, compiler-verified relationships.

const pb = createPageBuilderFromSections([hero, cta, testimonial], {
  strict: true
})

// The generated query becomes:
// `_type == "heroSection" => { title, subtitle, ctaHref }, ...`

// The renderer map is derived from the sections list

The strict: true option adds another layer of safety: if a block’s _type lacks a registered renderer, the system throws an error instead of silently skipping it. This turns a potential production failure into a build-time error—caught in CI, not by your users.

Enforce consistency with type safety and runtime checks

TypeScript plays a crucial role here. By defining your block union as a mapped type over block._type, the compiler ensures that every variant has exactly one renderer. Add a new section to the union without a corresponding component, and the build fails before deployment.

For parts the type system can’t validate—such as schema registration or the final GROQ string—you can add a runtime integrity check in your tests:

assertPageBuilderIntegrity({
  renderers,
  registeredTypes,
  query: pageBuilderFields
})

This single test fails loudly if any component of the system is out of sync, turning what was once a silent production bug into a visible CI alert.

Streamline Studio workflows for editors

The frontend isn’t the only place where duplication occurs. The Sanity Studio side often requires boilerplate to make the insert menu usable—copy-pasting preview components into every section schema and manually registering types. This adds friction for content editors and developers alike.

A dedicated plugin can automate this process. By scanning your sections list, it can:

• Auto-detect all *Section types and register them in the Studio.
• Generate visual previews using a filename convention (e.g., hero-section.png for a section named heroSection).
• Populate the insert menu with thumbnails, making it easier for editors to choose sections.

With this setup, adding a new section involves only defining the component and registering it in your sections list. The Studio plugin handles the rest—no per-schema configuration, no hand-maintained maps.

A scalable, maintainable architecture

The key insight is simple: treat your page builder’s infrastructure as a dependency, not as code you rewrite for each project. The sections remain yours—custom, branded, and unique—but the plumbing becomes a shared, tested, and type-safe layer.

This approach reduces boilerplate, prevents silent failures, and improves developer velocity. It also future-proofs your site against schema changes, query updates, and component drift. No more blank spaces on launch day.

As Sanity continues to power more marketing sites, teams that adopt this pattern will spend less time debugging and more time building—without sacrificing flexibility or design control.