VTEX IO headless: dos fuentes de verdad y el costo real

La tienda headless no falla en el front end. Falla cuando la apariencia y el contenido viven en bases distintas. La vitrina es una cosa y el esquema de contenido es otra. Quien los mantiene separados paga en retrabajo cada vez que una campaña pide una sección que el design system nunca previó.

Qué cambia de verdad cuando la tienda pasa a headless

VTEX describe el comercio headless (en inglés) como el uso de las funciones centrales de comercio por APIs REST, con la vitrina construida fuera de las soluciones de storefront de la propia plataforma. La misma página también declara que VTEX no ofrece autenticación headless para el comprador. Por eso la página de login sigue siendo nativa y la interfaz redirige a la persona a /login.

En resumen, ese es el cambio. Catálogo, precio, inventario, promoción y pedido siguen corriendo en el núcleo de comercio. Lo que sale es la capa que armaba la página.

FastStore (en inglés) es el kit que VTEX mantiene para esa capa: un proyecto Jamstack con un paquete Core, un SDK, un paquete de UI y un paquete de API. El design system vive en el paquete de UI, armado sobre componentes FastStore y estilizado con Sass.

O sea, el cambio no es que la tienda se vuelva código. El cambio es que la composición de la página deja de ser configuración dentro de la plataforma y pasa a ser un artefacto que el equipo construye, revisa y publica.

Contenido editorial no es dato de catálogo

Dos tipos de dato circulan en una vitrina headless, y cada uno obedece a su propia regla.

Dato de catálogo es un hecho sobre el producto: nombre, precio, stock, imagen, variante, categoría. Tiene un dueño, el núcleo de comercio, y cambia por operación de catálogo.

Contenido editorial es una decisión sobre la página: qué banner abre la home, el orden de los estantes de productos, el texto de una landing page, el sello de la campaña. No tiene dueño en el catálogo porque no describe el producto.

El CMS de VTEX (en inglés) documenta tipos de contenido como home, pdp, plp y landingPage, con componentes declarados en JSON Schema. Un componente es un grupo de campos (en inglés). Una sección es el componente que funciona como contenedor, y es la unidad que el editor arrastra y reordena.

Una sección puede apuntar a una colección, y ahí empieza la confusión. El estante de productos es editorial. Los productos dentro son catálogo. Cuando el equipo de campaña edita el estante y el equipo de catálogo edita la colección, los dos creen que cambiaron la página.

El retrabajo nace de esa mezcla. El problema no es el volumen de contenido, sino no saber de quién es cada campo. La taxonomía del NN/g (en inglés) separa cuatro modelos de organización: la navegación, la estructura de arquitectura de la información, la taxonomía y el modelo de contenido. El estante de productos pertenece al modelo de contenido, y el filtro que la misma palabra nombra pertenece a la taxonomía.

Por qué dos fuentes de verdad generan retrabajo

Un campo solo existe para quien lee si tres cosas coinciden: el design system lo renderiza, el esquema de contenido lo declara y el runtime lo mapea.

La guía de VTEX sobre componentes y secciones (en inglés) afirma que la vitrina hace un mapeo en tiempo de ejecución. La jerarquía de tipos de contenido, secciones y componentes se convierte en componentes de interfaz y HTML reales. Ese mapeo es código.

Cuando el esquema vive en una base y el design system vive en otra, el mapeo se rehace a mano en cada campaña. El editor ve un campo que la vitrina no renderiza, o la vitrina entrega una sección que ningún editor puede completar.

El plugin de contenido (en inglés) deja la dirección explícita. El comando generate-schema une esquemas de componentes, tipos de contenido y el esquema base de FastStore en un solo archivo, y upload-schema envía ese archivo al Schema Registry. El esquema es un artefacto del proyecto, versionado junto con el código.

Mantener los dos en la misma base hace revisable el mapeo, y eso pesa más que la preferencia de herramienta. NN/g trata los patrones de contenido como parte del design system (en inglés), con los mismos roles, responsabilidades y revisión periódica que los componentes de interfaz.

Qué se rompe en cada campaña

Tres fallas aparecen siempre, y todas vienen de esa separación.

El componente que solo existe en la vitrina. Alguien arma un hero de lanzamiento directo en el front end, fuera del tipo de contenido. Ese día, funciona. En la campaña siguiente el CMS no ofrece ese hero, y el trabajo se repite.

El campo que solo usa marketing. Sello de campaña, etiqueta, cuenta regresiva. Si el campo no está en el esquema, vive en un valor fijo dentro del código o en una hoja de cálculo que alguien pega a mano. Si está en el esquema pero ningún token del design system lo cubre, renderiza con el peso equivocado.

La promoción que el catálogo no conoce. Precio y promoción viven en el núcleo de comercio, no en el CMS. Una página que muestra un número escrito por el editor crea una segunda fuente de verdad para precio, y el checkout va a contradecirla.

La documentación del CMS legado (en inglés) agrega una cuarta trampa: los alcances. Un tipo de contenido con alcance pdp solo se puede usar en página de producto. El editor que quiere un bloque de campaña en la búsqueda descubre que el tipo no aparece, y el ticket va al equipo de front end.

NN/g lista el mismo problema desde el lado de la estructura (en inglés), en sitios que tratan cada ítem como unidad aislada y no ofrecen camino hacia lo relacionado.

Cuándo la tienda no debe ser headless

Headless es una capa de ingeniería que vas a mantener para siempre. Es la respuesta equivocada en tres casos comunes.

Catálogo pequeño. Cuando unas pocas decenas de productos cubren la oferta, la vitrina estándar ya resuelve búsqueda, página de producto y checkout. El proyecto headless compra un pipeline de build para resolver un problema que la tienda no tiene.

Equipo sin dueño del front end. Headless exige alguien responsable del build, del deploy, de las dependencias y del presupuesto de performance después del lanzamiento. Sin esa persona, la tienda se queda con el costo y pierde la ganancia.

Operación que cambia poco. Pocas campañas por año y poca variación editorial no justifican una capa nueva de composición. Una personalización del tema lo resuelve con menos superficie.

Hay también un límite técnico que conviene conocer antes de decidir. VTEX declara que no ofrece autenticación headless para el comprador (en inglés), así que la página de login sigue siendo nativa. Si la marca exige una pantalla de login diseñada desde cero, la plataforma no la entrega hoy.

Qué medir para saber si la arquitectura funciona

Seis números dicen si el proyecto se pagó solo. Todos salen de la propia tienda, no del proveedor.

Secciones declaradas contra secciones usadas. Cuenta las secciones y los tipos de contenido del esquema, después los que aparecen en páginas publicadas. Una sección que nadie usa es peso en el repositorio y una opción desperdiciada en la lista del editor.

Tiempo del briefing a la página publicada. Mide al mismo equipo antes y después, en el mismo tipo de campaña. Es el número que el proyecto existe para mover.

Tickets por campaña que necesitan un desarrollador. Si la cuenta sigue igual, el proyecto pagó el costo y mantuvo el problema.

Páginas cuyo contenido cambió sin deploy. Ese es el punto del CMS desacoplado, y la respuesta es binaria. O pasa, o el CMS es un trámite.

Conflictos de precio encontrados después de publicar la campaña. El número esperado es cero. Cualquier aparición significa una segunda fuente de verdad para precio.

Core Web Vitals en el percentil 75: LCP hasta 2,5 segundos, INP hasta 200 milisegundos, CLS hasta 0,1. FastStore declara que busca puntajes altos en pruebas como Lighthouse y Web Vitals, así que la métrica es parte de la promesa.

Dónde divergen las fuentes

Los artículos del NN/g no describen el mismo mantenimiento, y la diferencia cambia el presupuesto.

Patrones de contenido en el design system (en inglés) trata el contenido como parte del sistema, con mantenimiento anual. Taxonomía 101 (en inglés) ubica el vocabulario controlado en una capa separada, mantenida por quien gobierna el vocabulario y no por quien escribe la página.

Web Vitals define la aprobación en el percentil 75, medida en el campo. Los tres coinciden en que mantener la calidad exige a alguien responsable, con nombre.