Jetzt mit KI-gestütztem Page Building über den MCP-Server

Block-System

Wie Blöcke im Headless-Modell funktionieren - defineBlock, Instanzen, die Komponente, Context und der Data-Loader.

29. Juni 2026

Überblick

Blöcke sind die Bausteine jeder Cmssy-Seite. Im Headless-Modell ist ein Block eine React-Komponente in deinem eigenen Next.js-Repo, deklariert mit defineBlock und einem fields-Schema. Im Cmssy-Admin platzieren und konfigurieren Redakteure Block-Instanzen; deine Site rendert sie mit dem SDK. Ein Block hat drei Teile:

  • Schema (fields) — die editierbaren Felder im Admin
  • Komponente — die React-Komponente, die den Inhalt rendert
  • Registrierung — der Block wird zum Array in cmssy/blocks.ts hinzugefügt

Einen Block definieren

Ein Block wird mit defineBlock und einem fields-Schema deklariert, und seine Komponente leitet ihre Props aus genau diesem Schema ab: BlockProps<typeof props> - ein Feld wird also an exakt einer Stelle benannt. Block-Entwicklung führt komplett hindurch; Schema & Feldtypen listet alle Feldtypen.

Block-Instanzen

Wenn ein Redakteur deinen Block zu einer Seite hinzufügt, speichert Cmssy eine Block-Instanz:

{
  id: string;    // unique UUID for this instance
  type: string;  // matches your block's `type` (e.g. "hero")
  content: Record<string, unknown>;  // language-keyed field values
}

Inhalte werden pro Sprache gespeichert ({ en: {...}, pl: {...} }); das SDK löst die aktive Locale auf, bevor es content an deine Komponente übergibt - du liest die Felder also direkt.

Die Komponente, Context & Daten

Deine Komponente erhält { content, context, data }. content ist bereits für die aktive Locale aufgelöst und aus deinem Schema typisiert; context trägt locale und isPreview, dazu forms sowie auth / workspace, wenn deine App sie über buildBlockContext liefert; data ist das Ergebnis eines Server-Loaders.

Die Registrierung ist ein Array, cmssy/blocks.ts, und es ist die einzige Quelle der Wahrheit: Es steuert das Rendering, und der Editor lernt daraus über die SDK-Bridge das Schema jedes Blocks - der Picker zeigt also immer genau das, was deine Site rendern kann. Blöcke gehen mit dem Deploy deiner App live; einen separaten Block-Build oder -Publish gibt es nicht.

Layout-Blöcke

Header, Footer und andere geteilte Bereiche sind Layout-Blöcke — identisch mit Seiten-Blöcken, aber mit layoutPositions markiert (z. B. ["header"]) und von CmssyServerLayout pro Position gerendert.

Internationalisierung

Inhalte sind im CMS pro Sprache gespeichert und werden pro Request aufgelöst. Das Routing läuft über Pfad-Prefix (/pl/*), die Standard-Locale nutzt saubere URLs. Lies die aktive und die aktivierten Locales aus context.locale.

Nächste Schritte