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

Block-System

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

Last updated: 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

// blocks/hero/block.ts
import type { ComponentType } from "react";
import { defineBlock, fields } from "@cmssy/react";
import Component from "./src";

export const heroBlock = defineBlock({
  type: "hero",          // unique block type id, stored on each instance
  label: "Hero",
  component: Component as unknown as ComponentType<{ content: Record<string, unknown> }>,
  props: {
    heading: fields.singleLine({ label: "Heading" }),
    body: fields.richText({ label: "Body" }),
  },
});

Siehe Schema & Feldtypen für alle Feldtypen und Block-Entwicklung für die vollständige Anleitung.

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 }:

import type { CmssyBlockContext } from "@cmssy/react";

export default function Hero({ content, context }: {
  content: Record<string, unknown>;
  context?: CmssyBlockContext;
}) {
  const locale = context?.locale.current ?? "en";
  return <section><h1>{String(content.heading ?? "")}</h1></section>;
}

context enthält locale ({ current, default, enabled }) und isPreview (true im Editor), außerdem forms und — wenn config.auth gesetzt ist — auth ({ isAuthenticated, member }) und workspace ({ id, slug }). Für deine eigenen Models oder Records nutze createCmssyClient aus @cmssy/react. Um während SSR zu laden (crawlbar, ohne Lade-Flackern), gib dem Block einen loader — sein Ergebnis kommt als data-Prop an. Siehe Erweiterte Funktionen für beides.

Blöcke registrieren

// cmssy/blocks.ts
import { heroBlock } from "@/blocks/hero/block";
export const blocks = [heroBlock];

Dieses Array ist die einzige Quelle der Wahrheit: Es steuert das Rendering, und der Editor lernt das Schema jedes Blocks über die SDK-Bridge - so erscheint dein Block im Block-Picker des Admins. Es gibt keinen separaten Build- oder Publish-Schritt für Blöcke — Blöcke gehen live, wenn du deine Next.js-App deployst.

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

Block System - Cmssy Documentation