Przewodnik tworzenia bloków

Anatomia bloku

Blok Cmssy żyje w Twoim repozytorium Next.js jako folder w blocks/:

• block.ts — deklaruje blok przez defineBlock + fields (typ, etykieta i edytowalna schema)
• Hero.tsx — komponent React renderujący treść

Zarejestruj blok w cmssy/blocks.ts. Edytor czyta schema każdego bloku przez most SDK, więc dodanie bloku do strony renderuje formularz edycji z Twoich fields.

---

Zdefiniuj blok

// blocks/hero/block.ts
import { defineBlock, fields } from "@cmssy/react";
import Hero from "./Hero";

// Wyeksportowane osobno, żeby komponent mógł wyprowadzić z tego swoje propsy.
export const heroProps = {
  heading: fields.text({ label: "Heading", defaultValue: "Welcome" }),
  body: fields.richText({ label: "Body" }),
  ctaUrl: fields.link({ label: "CTA URL", defaultValue: "/signup" }),
  showCta: fields.boolean({ label: "Show CTA", defaultValue: true }),
};

export const heroBlock = defineBlock({
  type: "hero",
  label: "Hero",
  component: Hero,
  props: heroProps,
});

Typy pól: text, textarea, richText, markdown, number, date, datetime, boolean, color, media, link, url, email, select, radio, multiselect, relation, repeater, table, json, form, pageSelector. Zobacz Schema i typy pól.

---

Komponent bloku

Bloki otrzymują { content, context, data }. Treść jest już rozwiązana dla aktywnego języka, więc czytaj pola bezpośrednio.

// blocks/hero/Hero.tsx
import type { BlockProps } from "@cmssy/react";
import { heroProps } from "./block";

export default function Hero({ content, context }: BlockProps<typeof heroProps>) {
  // Typy wzięte ze schematu: heading to string, showCta to boolean.
  const { heading, showCta, ctaUrl } = content;
  const isPreview = context?.isPreview ?? false;

  return (
    <section>
      <h1>{heading}</h1>
      {showCta && <a href={ctaUrl}>Get started</a>}
    </section>
  );
}

BlockProps<typeof heroProps> sprawia, że schemat jest jedynym miejscem, w którym pole ma nazwę. Zmień nazwę heading, a komponent przestanie się kompilować - zamiast po cichu renderować nic, co zrobiłoby czytanie content.heading z Record<string, unknown>. Gdy blok ma loader, przekaż jego typ zwracany jako drugi argument: BlockProps<typeof heroProps, Posts> typuje też propa data.

context niesie locale ({ current, default, enabled }) i isPreview (true w edytorze), a także forms dla każdego formularza, do którego blok się odwołuje. auth i workspace są obecne, gdy Twoja aplikacja poda je przez buildBlockContext. UI zależne od języka czyta context.locale.enabled. Po własne modele lub rekordy sięgaj przez createCmssyClient; żeby pobierać podczas SSR, dodaj loader i czytaj wynik z data. Zobacz Zaawansowane funkcje i Loadery serwerowe.

---

Zarejestruj i wdróż

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

Uruchom pnpm dev, otwórz edytor strony, a Twój blok pojawi się w wyborze bloków. Wdróż aplikację Next.js, aby opublikować — nie ma osobnego kroku budowania czy publikowania bloku.

---

Następne kroki

• Schema i typy pól — wszystkie typy pól, repeatery, pola warunkowe, grupy
• Zaawansowane funkcje — bloki layoutu, stylowanie, server loadery