Sanity PageBuilder: Wie man sich vor versteckten Fehlern schützt

Die meisten Sanity-basierten Websites integrieren einen PageBuilder, der über eine einfache Benutzeroberfläche verwaltbare Abschnitte ermöglicht. Doch hinter dieser scheinbar einfachen Lösung versteckt sich ein strukturelles Problem: Jedes Mal, wenn ein neuer Abschnitt hinzugefügt wird, drohen stille Fehler, die erst in der Produktion auffallen. Warum wiederholen sich diese Fehler in fast jedem neuen Projekt? Und wie lässt sich dieses Risiko dauerhaft eliminieren?

Der unsichtbare Preis jedes neuen Abschnitts

Das Hinzufügen eines neuen Abschnitts in einem typischen Sanity- und Next.js-basierten PageBuilder erfordert in der Regel fünf manuelle Schritte – und genau hier liegt das Problem. Jeder dieser Schritte birgt das Risiko eines menschlichen Fehlers, der erst sichtbar wird, wenn die Seite bereits live ist:

• Schema-Definition: Ein neuer Abschnittstyp (*Section) muss im zentralen Schema definiert werden.
• GROQ-Abfrage: Die Abfrage muss so angepasst werden, dass die benötigten Felder des Abschnitts tatsächlich abgerufen werden.
• Komponenten-Implementierung: Die React-Komponente für die Darstellung des Abschnitts wird erstellt oder angepasst.
• Renderer-Zuordnung: Eine Abbildung zwischen dem Abschnittstyp (_type) und der zugehörigen Komponente muss definiert werden.
• Typsystem-Anpassung: Die TypeScript-Definition des Abschnitts muss in der Union der unterstützten Blöcke aktualisiert werden.

Wird nur einer dieser Schritte vergessen oder falsch ausgeführt, kann das zu unterschiedlichen, aber immer schwer zu diagnostizierenden Fehlern führen. Manche Abschnitte erscheinen leer, andere fehlen komplett in der Bearbeiteroberfläche oder liefern keine Daten, weil die GROQ-Projektion fehlt. Im schlimmsten Fall gibt es überhaupt keine Fehlermeldung – nur eine leere Fläche auf der veröffentlichten Seite.

Warum die Lösung in der Wiederverwendung liegt

Die fünf genannten Schritte sind nicht projekt-spezifisch. Lediglich die Komponentenlogik ist individuell und sollte nicht standardisiert werden. Die anderen vier Schritte – Schema-Definition, GROQ-Abfrage, Renderer-Zuordnung und Typsystem-Integration – folgen immer demselben Muster und werden dennoch in jedem neuen Projekt von Grund auf neu implementiert.

Diese Wiederholung ist nicht nur ineffizient, sondern auch fehleranfällig. Jedes Mal, wenn der Code neu geschrieben wird, besteht die Gefahr, dass kleine Abweichungen entstehen, die sich erst in der Produktion zeigen. Die Lösung liegt darin, diesen generischen Code in eine wiederverwendbare Bibliothek auszulagern und nur die projektspezifischen Abschnitte individuell zu gestalten.

Ein zentraler Ansatz für Konsistenz und Fehlervermeidung

Die Idee ist einfach: Statt die fünf Schritte pro Abschnitt manuell umzusetzen, wird ein zentrales System geschaffen, das diese Schritte automatisch und konsistent durchführt. Damit wird sichergestellt, dass keine Abhängigkeit zwischen Schema, Abfrage und Darstellung verloren geht. Ein bewährtes Muster dafür sind zwei Pakete, die aus dieser Notwendigkeit heraus entstanden sind:

• `@maciejtrzcinski/sanity-page-builder-core` für die Frontend-Logik
• `@maciejtrzcinski/sanity-plugin-section-builder` für die Integration in das Sanity Studio

Doch unabhängig von den Paketen ist das Prinzip entscheidend: Alle Abschnitte werden an einer zentralen Stelle definiert, und das System stellt sicher, dass Schema, Abfrage und Darstellung immer synchron bleiben.

Eindeutige Definition pro Abschnitt

Jeder Abschnitt wird durch ein einziges Objekt definiert, das Typ, Abfrage und Darstellung in sich vereint:

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

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

Durch diese zentrale Definition wird verhindert, dass Schema, Abfrage oder Darstellung separat gepflegt werden müssen. Wird ein neuer Abschnitt hinzugefügt, ist es unmöglich, die Abfrage zu vergessen, da sie direkt im Abschnittsobjekt definiert ist.

Automatisierte GROQ-Projektion und Renderer-Zuordnung

Ein zentraler Builder erstellt sowohl die Renderer-Zuordnung als auch die GROQ-Projektion automatisch aus der Liste der definierten Abschnitte:

const pb = createPageBuilderFromSections([hero, /* weitere Abschnitte */], {
  strict: true,
})

// Automatisch generierte Renderer-Zuordnung
pb.renderBlock // Leitet einen Block an den passenden Renderer weiter

// Automatisch generierte GROQ-Projektion
pb.query // `_type == "heroSection" => { title, subtitle, ctaHref }, …`

Der entscheidende Vorteil: Die GROQ-Projektion wird nicht manuell neben den Abschnitten definiert, sondern direkt aus denselben Daten abgeleitet. Dadurch entfällt die Gefahr, dass Schema und Abfrage nicht synchron sind. Die Option strict: true stellt zudem sicher, dass jeder Abschnittstyp einen zugewiesenen Renderer hat – andernfalls wird ein Fehler geworfen, statt der Abschnitt einfach ignoriert zu werden.

Typsicherheit als letzte Absicherung

Das System ist generisch über die Block-Union des Projekts definiert, sodass die Renderer-Zuordnung als gemappter Typ über block._type implementiert wird. Der TypeScript-Compiler stellt sicher, dass für jeden Abschnittstyp genau ein Renderer existiert und dieser korrekt typisiert ist. Wird ein neuer Abschnitt hinzugefügt, ohne den Renderer zu registrieren, schlägt der Build fehl – noch bevor der Fehler in die Produktion gelangt.

Für Teile, die nicht durch das Typsystem abgedeckt werden können (wie die registrierten Schema-Typen oder die GROQ-Projektion), gibt es eine zusätzliche Integritätsprüfung, die in den Tests ausgeführt wird:

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

Diese Prüfung stellt sicher, dass alle Komponenten – Renderer, registrierte Typen und Abfragen – konsistent bleiben. Jede Abweichung führt zu einem sofortigen Fehlschlag im Continuous Integration-System, sodass Fehler nicht erst in der Produktion auffallen.

Vereinfachung der Bearbeiteroberfläche im Studio

Ein weiterer wiederkehrender Aufwand in Sanity-Projekten ist die Konfiguration der Bearbeiteroberfläche. Standardmäßig zeigt das Studio eine Liste von Typennamen an, und für jeden Abschnitt muss manuell eine Vorschau-Komponente definiert werden. Das führt zu redundantem Code und einer unübersichtlichen Oberfläche für Redakteure.

Das Plugin sanity-plugin-section-builder löst dieses Problem, indem es Vorschauen automatisch erkennt und global bereitstellt:

// sanity.config.ts
plugins: [sectionBuilder(SECTIONS)]

// Definition der Feldtypen für Dokumentfelder
fields: [sectionField(SECTIONS, { group: 'content' })]

Jeder neue Abschnittstyp (*Section) wird automatisch erkannt. Vorschauen werden über eine Namenskonvention aufgelöst: Wird ein Abschnitt heroSection genannt, muss nur eine Datei hero-section.png im Vorschau-Ordner abgelegt werden. Diese Vorschau erscheint dann im Array-Editor, im Bearbeitungsbereich und in der nativen Einfüge-Menü-Oberfläche. Manuelle Zuordnungen und wiederholter Code entfallen vollständig – die Redakteure erhalten eine visuelle, intuitive Oberfläche, während die Entwickler Code einsparen.

Fazit: Weniger Fehler, mehr Effizienz

Die Lösung für die wiederkehrenden Fehler im Sanity PageBuilder liegt nicht in der komplexen Neuimplementierung, sondern in der konsequenten Trennung von generischem Code und projektspezifischen Abschnitten. Durch die Auslagerung der generischen Logik in wiederverwendbare Pakete oder Module wird sichergestellt, dass Schema, Abfrage und Darstellung immer synchron bleiben. Gleichzeitig wird die Bearbeiteroberfläche für Redakteure vereinfacht und standardisiert.

Das Ergebnis: Keine leeren Abschnitte mehr in der Produktion, keine manuellen Anpassungen in fünf verschiedenen Dateien und keine stille Drift zwischen Schema und Abfrage. Stattdessen ein zuverlässiges, wartbares System, das Entwickler und Redakteure gleichermaßen unterstützt – und das in jedem neuen Projekt sofort einsatzbereit ist.

Die Zeit, die bisher für die Fehlersuche und manuelle Synchronisation aufgewendet wurde, kann nun in die eigentliche Entwicklung innovativer Abschnitte und Features investiert werden.