Sistema de bloques
Cómo funcionan los bloques en el modelo headless - defineBlock, instancias, el componente, el context y el data loader.
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
Un bloque se declara con defineBlock y un esquema fields, y su componente deriva las props de ese mismo esquema con BlockProps<typeof props>, así que un campo se nombra en un único sitio. Desarrollo de bloques lo recorre de principio a fin; Esquema y tipos de campo lista todos los tipos.
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 }. content ya viene resuelto para el idioma activo y tipado desde tu esquema; context lleva locale e isPreview, además de forms, y auth / workspace cuando tu app los aporta mediante buildBlockContext; data es lo que devolvió un loader de servidor.
El registro es un array, cmssy/blocks.ts, y es la única fuente de verdad: impulsa el renderizado y el editor aprende de él el esquema de cada bloque por el puente del SDK, así que el selector siempre coincide con lo que tu sitio puede renderizar. Los bloques salen con el despliegue de tu app: no hay un paso aparte de build ni de publicación.
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