Ir al contenido

Construir páginas con blocks

Un constructor de páginas es una lista de secciones donde cada sección elige su forma: una portada con título e imagen, un texto, una cita, una galería. Eso es un campo blocks. Esta guía recorre el caso entero con el código de la demo del repositorio (apps/demo): declararlo, editarlo en el panel, pintarlo en Astro y, si ya guardabas las secciones en un json, pasarlas a blocks.

  • Filas que tienen todas la misma forma (los enlaces de un menú, unas preguntas frecuentes): un array.
  • Filas de formas distintas que quien edita elige y ordena: blocks, que es lo de esta guía.
  • Un texto con formato dentro de una sola sección: un richText, que también cabe como subcampo de un bloque.
  • Datos con una forma que no quieres tipar ni consultar: json.

La colección pages de la demo tiene un título, un slug y las sections:

cms.config.ts
const pages = defineCollection({
slug: 'pages',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'slug', type: 'text', required: true, unique: true, index: true },
{
name: 'sections',
type: 'blocks',
labels: { singular: 'Sección', plural: 'Secciones' },
blocks: [
{
slug: 'hero',
label: 'Portada',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'align', type: 'radio', options: ['left', 'center'], defaultValue: 'left' },
{ name: 'image', type: 'upload', to: 'ssd' },
],
},
{ slug: 'rich-text', label: 'Texto', fields: [{ name: 'content', type: 'richText' }] },
{
slug: 'quote',
label: 'Cita',
fields: [
{ name: 'text', type: 'textarea', required: true },
{ name: 'author', type: 'text' },
],
},
{
slug: 'gallery',
label: 'Galería',
fields: [
{ name: 'image1', type: 'upload', to: 'ssd' },
{ name: 'image2', type: 'upload', to: 'ssd' },
{ name: 'image3', type: 'upload', to: 'ssd' },
],
},
],
},
],
})

Tres cosas que salen de ahí:

  • El slug de un bloque va en minúsculas, con dígitos y guiones (rich-text, no richText): es el blockType de sus filas y el final del nombre de su tabla, y defineConfig lanza INVALID_BLOCK_SLUG con cualquier otro. En la tabla, el guion es un guion bajo: rich-text da pages_sections_rich_text.
  • Cada tipo de bloque es una tabla hija, y la tabla del documento no cambia. Con cms db:migrate salen pages_sections_hero, pages_sections_rich_text, pages_sections_quote y pages_sections_gallery, todas nuevas: es una migración que solo añade. Ver Tablas hijas.
  • Los subcampos son los de una fila: los trece tipos de un valor y una columna —aquí text, textarea, radio, richText y upload—. Un group, un point o otra lista dentro de una fila se rechazan al validar el config.
Ventana de terminal
pnpm cms db:migrate # escribe migrations/<fecha>_<nombre>/migration.sql, léelo
pnpm cms db:apply # lo aplica a la D1 local

cms db:generate escribe además el tipo de cada fila en .cms/types.d.ts, como una unión que se estrecha por blockType:

.cms/types.d.ts
export interface Page {
id: string
createdAt: Date
updatedAt: Date
title: string
slug: string
sections: (
| { id: string; blockType: 'hero'; title: string; align: 'left' | 'center' | null; image: string | Medio | null }
| { id: string; blockType: 'rich-text'; content: unknown | null }
| { id: string; blockType: 'quote'; text: string; author: string | null }
| { id: string; blockType: 'gallery'; image1: string | Medio | null; image2: string | Medio | null; image3: string | Medio | null }
)[]
}

En /admin/collections/pages el campo es una lista de filas plegables. «Añadir sección» abre un menú con el catálogo (cada bloque con su label y su admin.description), y elegir uno añade una fila de ese tipo, con solo sus subcampos. Cada fila se sube, se baja, se duplica y se elimina desde su menú, con Alt+↑ y Alt+↓, o arrastrando su asa. El tipo de una fila no se cambia: se elimina y se añade otra. El detalle, con el teclado, los errores por fila y lo que pasa con un tipo que el config ya no declara, está en Editar una lista en el panel.

Una página de Astro lee el documento con la API local y recorre sections con un switch sobre blockType. Esta es, abreviada, la src/pages/[slug].astro de la demo:

src/pages/[slug].astro
---
import RichText from '@kevolution-co/cms/rich-text/RichText.astro'
import Layout from '@/layouts/Layout.astro'
export const prerender = false
const { slug } = Astro.params
const { pages, ssd } = Astro.locals.cms.collections
const page =
slug === undefined
? null
: await pages.findOne({ where: { slug: { equals: slug } }, depth: 1, overrideAccess: true })
if (page === null) return new Response('No existe ninguna página con ese slug.', { status: 404 })
---
<Layout title={page.title}>
{
page.sections.map((block) => {
switch (block.blockType) {
case 'hero':
return <h2>{block.title}</h2>
case 'rich-text':
return <RichText value={block.content} />
case 'quote':
return <blockquote>{block.text}</blockquote>
case 'gallery':
return [block.image1, block.image2, block.image3].map((image) => /* … */)
default:
block satisfies never
return null
}
})
}
</Layout>
  • Cada case estrecha la fila. Dentro de case 'hero', block tiene title, align e image, y ningún subcampo de los otros bloques.
  • El default hace que olvidar un bloque sea un error de compilación. Si añades un bloque al config y no un case, en el default la fila deja de ser never y astro check falla. En ejecución no pinta nada.
  • depth: 1 trae los ficheros como documento. Sin él, image es el id pelado de la biblioteca. Con depth, la imagen es string | Medio | null en el tipo, y la demo la estrecha con una función de dos líneas (resolved) antes de pintarla: ver Relaciones: depth.
  • overrideAccess: true porque la API local es anónima por defecto y esta ruta decide qué se muestra. La demo no es pública para escribir: pages declara access y solo un administrador crea, edita o borra.
  • Una ruta [slug] en la raíz no tapa /admin. Astro prefiere la ruta con nombre exacto, así que el panel y la API REST siguen donde estaban; a cambio, una página con el slug admin no se vería nunca.

Las filas llegan ya ordenadas, con su id y su blockType, y nunca con parent ni _order. Ver Leer listas.

Una lista que llega reemplaza las filas que había, y cada fila lleva su blockType y los subcampos de su bloque, sin id (el servidor pone uno). El seed de la demo crea así sus dos páginas:

await cms.collections.pages.create(
{
slug: 'sobre-esta-demo',
title: 'Sobre esta demo',
sections: [
{ blockType: 'hero', title: 'Un constructor de páginas con blocks', align: 'center', image: imageId },
{ blockType: 'quote', text: 'El tipo de cada sección es fijo.', author: 'La guía' },
],
},
{ overrideAccess: true },
)

blockType es obligatorio y tiene que ser uno del catálogo: { blockType: 'otro' } no compila, y una fila de un tipo que no existe es UNKNOWN_BLOCK. Para el texto con formato de un rich-text, markdownToLexical, de @kevolution-co/cms/rich-text/convert, convierte markdown al árbol que guarda el campo.

Si hoy guardas las secciones (o los enlaces de un menú) en un campo json, pasar a array o blocks depende de dónde vive.

Un global vive en KV y una lista es el JSON de sus filas bajo una clave, así que no hay migración: declara la lista y guarda. Es lo que hizo la demo con nav, que era un json con [{ "href": "/", "label": "Inicio" }]:

cms.config.ts
{
name: 'nav',
type: 'array',
fields: [
{ name: 'href', type: 'text', required: true },
{ name: 'label', type: 'text', required: true },
],
}
  • Las filas guardadas sin id se leen. Cada una recibe su posición como id ("0", "1"), la misma en cada lectura, y el primer guardado de esa lista lo persiste. Un guardado de otro campo (el tagline) no la toca.
  • Los subcampos tienen que ser exactamente las claves que ya guardabas. Una clave que el config no declara (target, por ejemplo) o una fila a la que le falta un campo required hace que guardar el global falle, aunque lo que guardes sea otro campo: UNKNOWN_FIELD o REQUIRED, con la ruta de la fila (nav.0.target). Revisa el valor guardado antes de cambiar el config. Si ya lo has cambiado, el panel enseña las filas y deja corregirlas.
  • Un valor que no es un array de objetos se lee como si la lista no existiera ([]) y se avisa en la consola.

Una colección guarda las filas en tablas hijas, y ninguna migración copia lo que había en la columna json: la migración que genera cms db:migrate crea la tabla hija y quita la columna, y las filas se pierden salvo que las copies tú. El CMS no escribe esa copia por ti: es SQL tuyo, en la propia migración, entre el CREATE TABLE y el DROP COLUMN.

Con posts.meta (un json con [{ "label": "…", "url": "…" }]) pasando a un array llamado links:

  1. Declara links y quita meta del config, y ejecuta pnpm cms db:migrate. Con terminal te pide confirmación, porque quitar una columna pierde sus datos. Sale esto:

    migrations/<fecha>_<nombre>/migration.sql
    CREATE TABLE `posts_links` (
    `parent` text NOT NULL,
    `id` text NOT NULL,
    `_order` integer NOT NULL,
    `label` text,
    `url` text,
    CONSTRAINT `posts_links_pk` PRIMARY KEY(`parent`, `id`)
    );
    --> statement-breakpoint
    ALTER TABLE `posts` DROP COLUMN `meta`;
  2. Añade la copia entre las dos sentencias. Una fila de una tabla hija necesita parent (el documento), un id y un _order (la posición, desde 0):

    migrations/<fecha>_<nombre>/migration.sql
    CREATE TABLE `posts_links` (
    `parent` text NOT NULL,
    `id` text NOT NULL,
    `_order` integer NOT NULL,
    `label` text,
    `url` text,
    CONSTRAINT `posts_links_pk` PRIMARY KEY(`parent`, `id`)
    );
    --> statement-breakpoint
    INSERT INTO posts_links (parent, id, _order, label, url)
    SELECT p.id, lower(hex(randomblob(16))), j.key, j.value ->> 'label', j.value ->> 'url'
    FROM posts p, json_each(CASE WHEN json_valid(p.meta) AND json_type(p.meta) = 'array' THEN p.meta ELSE '[]' END) j
    WHERE j.type = 'object';
    --> statement-breakpoint
    ALTER TABLE `posts` DROP COLUMN `meta`;
  3. Aplícala en local, mira el resultado y solo entonces en remoto:

    Ventana de terminal
    pnpm cms db:apply
    npx wrangler d1 execute DB --local --command "SELECT parent, _order, label FROM posts_links ORDER BY parent, _order"
    pnpm cms db:apply --remote

    cms db:generate --check sigue en verde: compara el snapshot.json, no el SQL que has editado.

Lo que hace cada pieza, y por qué no es un json_each(p.meta) a secas:

  • j.key es la posición de cada elemento (0, 1, 2…), así que el orden del array se conserva.
  • lower(hex(randomblob(16))) es el id de la fila: 32 caracteres, que es un id válido, y único por construcción. Si lo prefieres, CAST(j.key AS TEXT) también vale, porque el id solo tiene que ser único dentro del documento.
  • El CASE deja pasar solo los arrays. json_each sobre un null de SQL no devuelve filas, pero sobre una cadena vacía o un JSON roto lanza un error. Sobre un null de JSON o un número devuelve una fila sin posición, que viola el NOT NULL de _order, y sobre un texto ("hola") la fila hace fallar el ->>. Sobre un objeto devuelve una fila por clave: con valores que no son JSON ("label": "x") falla, y con números, null u objetos dentro no falla y deja filas de basura, con el nombre de la clave como _order. Los errores hacen fallar la migración entera: se aplica en una sola transacción y no queda nada aplicado (en local, comprobado), pero no avanza.
  • WHERE j.type = 'object' salta los elementos que no son un objeto (un 7, una cadena, un null) en lugar de crear filas vacías. Esa fila no se copia y su posición queda sin usar: no importa, solo ordena.
  • ->> devuelve NULL para una clave que falta o un null, y el valor tal cual para el resto. Lo que no declares como subcampo no se copia: una clave target del json se pierde con la columna.

Después de migrar:

  • maxRows vale 100 por defecto. La migración no lo mira, así que una lista de 120 filas se copia entera y se lee, pero no se puede volver a guardar hasta que declares un maxRows mayor (hasta 1000) o quites filas: MAX_ROWS. Antes de migrar, mira cuál es la mayor: SELECT max(json_array_length(meta)) FROM posts WHERE json_valid(meta) AND json_type(meta) = 'array'.
  • Una celda required que salió vacía (una fila a la que le faltaba la clave) no impide la migración, pero sí guardar esa lista: el panel marca la celda y la rellenas. Los subcampos de la migración no llevan NOT NULL.
  • La columna desaparece con la migración. El código desplegado que lea meta falla entre db:apply --remote y el deploy del código nuevo: hazlo en una ventana de mantenimiento, o en el patrón de dos migraciones y una copia en medio de Convertir un campo en hasMany, donde la columna se quita cuando ya nadie la lee.

Cada tipo de bloque es su tabla, y _order es la posición en la lista entera, no en su tabla: así que se copia una tabla por tipo, con la misma j.key. Un json con [{ "blockType": "hero", "title": "…" }, { "blockType": "quote", "text": "…" }] a sections:

migrations/<fecha>_<nombre>/migration.sql
INSERT INTO pages_sections_hero (parent, id, _order, title)
SELECT p.id, lower(hex(randomblob(16))), j.key, j.value ->> 'title'
FROM pages p, json_each(CASE WHEN json_valid(p.sections) AND json_type(p.sections) = 'array' THEN p.sections ELSE '[]' END) j
WHERE j.type = 'object' AND j.value ->> 'blockType' = 'hero';
--> statement-breakpoint
INSERT INTO pages_sections_quote (parent, id, _order, text, author)
SELECT p.id, lower(hex(randomblob(16))), j.key, j.value ->> 'text', j.value ->> 'author'
FROM pages p, json_each(CASE WHEN json_valid(p.sections) AND json_type(p.sections) = 'array' THEN p.sections ELSE '[]' END) j
WHERE j.type = 'object' AND j.value ->> 'blockType' = 'quote';

Una fila cuyo blockType no es de ningún INSERT no se copia. Los upload y los relationship se copian como el id que ya guardabas, y su clave foránea hace fallar la migración (FOREIGN KEY constraint failed) si ese id ya no existe: límpialo antes de migrar.

  • No se puede filtrar ni ordenar por un subcampo de una lista: where, sort y select sobre sections.title son un QueryError. Las consultas sobre filas están en #227. Para buscar páginas por algo que está en un bloque, saca ese dato a un campo de la colección (title, slug).
  • Una lista que llega reemplaza la anterior entera, y sin If-Match dos guardados a la vez son last-write-wins sobre toda ella (el panel no manda If-Match).
  • Cada tipo de bloque cuenta como una tabla en las sentencias de un guardado: 3T + 2 en un update. La colección pages tiene T = 4, y un documento con muchas listas puede pasar de las 50 consultas del plan Free de D1. Ver el límite de sentencias.
  • Las tablas hijas no llevan clave foránea al documento: un DELETE a mano contra D1 deja filas huérfanas.

El resto de límites —maxRows, el tamaño de una lista, UNKNOWN_BLOCK, qué pasa en un global— están en Campos y en Limitaciones.