ADR-0008 · Vista previa de borradores del lado del servidor, no del cliente¶

Estado: aceptado
Decisores: hquintero
Fecha de la decisión: 2026-09-21

Contexto y problema¶

El storefront consume de Payload el JSON publicado de cada página, con una revalidación de 60 segundos. Mientras un editor trabaja, sus cambios quedan en un borrador que nadie renderiza: para verlos hay que publicar, es decir, exponerlos a los clientes antes de haberlos validado.

Payload trae vista previa en vivo, pero con dos implementaciones distintas y la elección no es reversible sin reescribir el renderizador de bloques. Había que decidir antes de empezar.

La restricción que pesó: el renderizador de bloques del storefront son componentes de servidor y varios bloques resuelven datos que el navegador no tiene, en particular las grillas de productos, que consultan Algolia desde el servidor.

Opciones consideradas¶

Del lado del servidor (RefreshRouteOnSave), la elegida. Payload avisa al marco que guardó; el storefront vuelve a pedir la página al servidor.
Del lado del cliente (useLivePreview). Payload manda el contenido del formulario en el mensaje y la página se repinta en el navegador, sin consultar al servidor.
No hacer nada y seguir publicando para ver los cambios.

Decisión¶

Se eligió la variante del lado del servidor. El mensaje que manda el admin no lleva datos: es solo un aviso de que hubo un guardado, y el contenido viaja por el mismo camino que usa un visitante cualquiera.

La razón principal es que no hay un segundo renderizador que mantener. La variante del cliente obliga a que el render de la página sea código de cliente, lo que significa reescribir los bloques y resolver en el navegador lo que hoy se resuelve en el servidor, empezando por las consultas a Algolia de las grillas de productos. Serían dos caminos de render en paralelo que pueden divergir, y una divergencia ahí es exactamente lo que la vista previa debería evitar: mostrarle al editor algo distinto de lo que verá el cliente.

El costo es latencia. Cada guardado dispara un renderizado completo, que hoy tarda alrededor de un segundo. Para un catálogo que además consulta Algolia, mantener un solo camino de render vale más que ese segundo.

Consecuencias¶

Positivas¶

Las páginas siguen siendo componentes de servidor; no se tocó el renderizador de bloques.
Lo que ve el editor se arma con el mismo código que sirve al público, así que no puede diverger.
El navegador del editor nunca ve el token de servicio: la autenticación contra Payload ocurre entre servidores.
Agregar un bloque nuevo no exige tocar nada de la vista previa.

Negativas / deuda asumida¶

Alrededor de un segundo de retraso entre el guardado y el cambio visible. No es una edición "en vivo" en el sentido literal.
El autoguardado quedó atado a ese costo: se subió de 100 ms a 800 ms en Pages y Posts porque a 100 ms los refrescos se encimaban. Si la página se vuelve más lenta, ese número hay que volver a subirlo.
Depende de un usuario de servicio con permisos de administrador. La colección Users no define roles: cualquier usuario autenticado puede todo, incluido crear y borrar usuarios. La cuenta que lee borradores es, de hecho, un administrador cuya contraseña vive en el .env del storefront. Acotar eso requiere un modelo de roles en el CMS, que es trabajo aparte.
La cadena tiene cuatro puntos de configuración y tres fallan en silencio: secreto, usuario de servicio, origen del CMS y frame-ancestors. Ninguno produce un error visible en el panel. La guía de integración lista los síntomas.
frame-ancestors deja de ser 'none': se permite embeber el storefront desde el origen del CMS. Es una excepción acotada y explícita sobre lo definido en el ADR-0007, y cae sola a 'none' si la variable no está definida.