Teraz z AI - twórz strony przez serwer MCP
Documentation

System bloków

Jak działają bloki w modelu headless - defineBlock, instancje, komponent i context.

Last updated: June 7, 2026

Przegląd

Bloki to jednostki budulcowe każdej strony cmssy. W modelu headless blok to komponent React w Twoim repozytorium Next.js, zadeklarowany przez defineBlock i schemę fields. Admin cmssy pozwala edytorom umieszczać i konfigurować instancje bloków; Twoja strona renderuje je przez SDK. Blok ma trzy części:

  • Schema (fields) — edytowalne pola pokazywane w adminie
  • Komponent — komponent React renderujący treść
  • Rejestracja — blok dodany do tablicy cmssy/blocks.ts

Definiowanie bloku

// 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",          // unikalny typ bloku, zapisany na instancji
  label: "Hero",
  component: Component as unknown as ComponentType<{ content: Record<string, unknown> }>,
  props: {
    heading: fields.singleLine({ label: "Heading" }),
    body: fields.richText({ label: "Body" }),
  },
});

Zobacz Schema i typy pól po wszystkie typy pól, oraz Tworzenie bloków po pełny przewodnik.

Instancje bloków

Gdy edytor doda Twój blok do strony, cmssy zapisuje instancję bloku:

{
  id: string;    // unikalny UUID tej instancji
  type: string;  // pasuje do `type` bloku (np. "hero")
  content: Record<string, unknown>;  // wartości pól per język
}

Treść jest zapisana per język ({ en: {...}, pl: {...} }); SDK rozwiązuje aktywny język przed przekazaniem content do komponentu, więc czytasz pola bezpośrednio.

Komponent i context

Twój komponent otrzymuje { content, context }:

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 to { locale: { current, default, enabled }, isPreview }. UI zależne od języka czyta context.locale.enabled; isPreview jest true w edytorze. Po dane workspace, własne modele, rekordy lub formularze użyj createCmssyClient z @cmssy/react zamiast context.

Rejestracja bloków

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

Ta tablica to jedyne źródło prawdy: napędza renderowanie, a edytor poznaje schemę każdego bloku przez most SDK, więc Twój blok pojawia się w wyborze bloków. Nie ma osobnego kroku budowania ani publikowania — bloki trafiają na produkcję gdy wdrażasz aplikację Next.js.

Bloki layoutu

Header, footer i inne współdzielone regiony to bloki layoutu — takie same jak bloki strony, ale oznaczone layoutPositions (np. ["header"]) i renderowane przez CmssyServerLayout per pozycja.

Internacjonalizacja

Treść jest kluczowana językiem w CMS i rozwiązywana per żądanie. Routing jest przez prefiks ścieżki (/pl/*), domyślny język używa czystych URL-i. Czytaj aktywny i włączone języki z context.locale.

Następne kroki

System bloków - Dokumentacja Cmssy