Sistema de bloques

Visión general

Los bloques son las unidades de construcción de cada página de Cmssy. En el modelo headless, un bloque es un componente React en tu propio repositorio Next.js, declarado con defineBlock y un esquema fields. El admin de Cmssy permite a los editores colocar y configurar instancias de bloques; tu sitio las renderiza con el SDK. Un bloque tiene tres partes:

• Esquema (fields) — los campos editables que se muestran en el admin
• Componente — el componente React que renderiza el contenido
• Registro — el bloque añadido a tu array de cmssy/blocks.ts

Definir un bloque

// 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" }),
  },
});

Consulta Esquema y tipos de campo para todos los tipos de campo, y Desarrollo de bloques para la guía completa.

Instancias de bloques

Cuando un editor añade tu bloque a una página, Cmssy guarda una instancia de bloque:

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

El contenido se guarda por idioma ({ en: {...}, pl: {...} }); el SDK resuelve la locale activa antes de pasar content a tu componente, así que lees los campos directamente.

El componente, el context y los datos

Tu componente recibe { 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 lleva locale ({ current, default, enabled }) e isPreview (true dentro del editor), además de forms, y — cuando config.auth está definido — auth ({ isAuthenticated, member }) y workspace ({ id, slug }). Para tus propios modelos o registros, obtén los datos con createCmssyClient de @cmssy/react. Para cargar durante el SSR (indexable, sin parpadeo de carga), dale al bloque un loader — su resultado llega como la prop data. Consulta Funciones avanzadas para ambos.

Registrar bloques

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

Ese array es la única fuente de verdad: impulsa el renderizado, y el editor aprende el esquema de cada bloque a través del puente del SDK, por lo que tu bloque aparece en el selector de bloques del admin. No hay un paso separado de build o publicación de bloques — los bloques se publican cuando despliegas tu aplicación Next.js.

Bloques de layout

El header, el footer y otras regiones compartidas son bloques de layout — iguales que los bloques de página pero marcados con layoutPositions (p. ej. ["header"]) y renderizados por CmssyServerLayout por posición.

Internacionalización

El contenido se guarda por idioma en el CMS y se resuelve por petición. El enrutamiento es por prefijo de ruta (/pl/*), y la locale por defecto usa URL limpias. Lee la locale activa y las habilitadas desde context.locale.

Próximos pasos

• Desarrollo de bloques — guía completa: definir, componente, registrar, desplegar
• Esquema y tipos de campo — todos los tipos de campo, repeaters, grupos
• Funciones avanzadas — bloques de layout, estilos, loaders de servidor