Sanity.io Headless CMS Tutorial: El CMS que Construyes Tú Mismo (No al Revés)

Estás Usando Sanity.io al Revés

El 90% de los desarrolladores trata Sanity como un CMS headless con esteroides. Definís schemas, exponéis un API REST, montáis un frontend que fetchea contenido.

Y funciona. Pero estáis perdiendo el 80% de lo que Sanity puede hacer por vosotros.

*La sabiduría convencional dice: define tus modelos de contenido primero, expónlos por API, y renderiza en el frontend. *

La realidad es que Sanity invierte esa lógica. No es un CMS con un API colgado. Es una base de datos de documentos en tiempo real con un React UI desacoplado, un query language propio (GROQ) capaz de hacer joins en tiempo de consulta, y un modelo de schemas sin migraciones que permite iterar a velocidad de código.

La mayoría de los tutoriales os enseñan a montar Sanity como si fuera WordPress con GraphQL. Cread contenidos, llamad a la API, mostrad en pantalla. Eso funciona, pero no aprovecha la arquitectura real de Sanity: el Content Lake.

El Content Lake no es una base de datos relacional. Es un almacén de documentos JSON donde cada contenido es un nodo atómico. Y GROQ —no REST, no GraphQL— es el lenguaje diseñado para navegar ese grafo. Las proyecciones en tiempo de consulta son el superpoder que el 90% ignora.

El Error de Tratar Sanity Como un REST API

Cuando montáis Sanity como un REST API estándar, hacéis esto:

Definís un schema de post con campos anidados.
Creáis un endpoint que devuelve el post entero.
En el frontend, filtráis y transformáis los datos en JSX.

Funciona. Pero cada petición devuelve datos que no necesitáis. Cada componente que renderiza el mismo post desde distinto ángulo tiene que hacer su propia transformación. Y si queréis datos relacionados (autor, categorías, posts similares), necesitáis múltiples llamadas o un schema hinchado.

❌ Enfoque REST tradicional: Schema monolítico → endpoint fijo → transformación en frontend.

✅ Enfoque Sanity real: Documentos atómicos → proyección GROQ → datos exactos por componente.

GROQ te permite hacer en una sola consulta lo que en REST necesitarías tres endpoints. Mira este ejemplo:

Una sola petición. Tres colecciones relacionadas. Proyección parcial. Joins en tiempo de consulta. Sin resolvers, sin endpoints adicionales, sin schemas complejos de GraphQL.

*Eso no es un CMS. Eso es una base de datos de documentos con un lenguaje de consulta que compite con SQL para datos semi-estructurados. *

GROQ: El Query Language que Nadie Aprende (y Debería)

GROQ es el activo infravalorado de Sanity. La mayoría lo ignora porque "ya saben GraphQL". Error.

GraphQL sobre Sanity añade una capa de abstracción que:

Duplica la definición de tipos.
Introduce resolvers que son ida y vuelta al mismo Content Lake.
Necesita schema stitching si tenéis múltiples fuentes.
Oculta la capacidad de proyección parcial nativa de Sanity.

GROQ, en cambio, es un lenguaje de query diseñado específicamente para documentos JSON anidados con referencias. No necesitáis definir resolvers. No necesitáis schemas GraphQL. Escribís la query que produce exactamente el JSON que vuestro componente necesita.

Esto es especialmente potente cuando tenéis múltiples consumidores del mismo contenido:

Mismo contenido. Dos proyecciones distintas. El schema no cambia. Cada consumidor recibe exactamente lo que necesita y nada más.

Portable Text: El Formato que Te Libera del Vendor Lock-In

Sanity no guarda el contenido como HTML. Lo guarda como un array de objetos JSON tipados. Cada bloque (párrafo, imagen, código, embed) es un objeto con _type, valor, y metadatos.

Esto se llama Portable Text y es, probablemente, la decisión arquitectónica más inteligente de Sanity.

❌ CMS tradicional: El editor escribe HTML → guardas HTML → renderizas HTML en web. Te has casado con ese formato.

✅ Portable Text: El editor escribe bloques estructurados → guardas JSON → renderizas como HTML, texto plano, RSS, o lo que necesites.

Un renderer de Portable Text es un pipeline de componentes React (o Vue, o Svelte, o Swift) que mapea cada _type a un componente:

Ese mismo JSON que renderizáis en web puede renderizarse en iOS con un renderer Swift, o en un email como texto plano. El contenido no depende del formato de salida. Lo escribís una vez, lo consumís en cualquier lado.

El Patrón que el 90% Ignora: Schemas Atómicos + Proyecciones GROQ

El anti-patrón más común en proyectos Sanity es la normalización prematura. Desarrolladores acostumbrados a SQL empiezan a dividir el contenido en decenas de tipos interconectados con referencias profundas. El resultado: queries lentas, editores frustrados que tienen que navegar cinco referencias para editar una página, y un schema que replica una base de datos relacional en un almacén de documentos.

*El enfoque Sanity-idiomático es opuesto: documentos planos, referencias ligeras, y proyecciones GROQ para componer. *

1. Schemas Atómicos

No creéis un schema de "página web". Cread tipos pequeños y reutilizables: block, image, link, person, testimonial, pricingTier. Luego componedlos con arrays y referencias.

2. Proyecciones GROQ Antes de la UI

Antes de escribir un solo componente de React, escribid las queries GROQ que vais a necesitar. Esto revela gaps en el modelado antes de que lleguéis al frontend, y os obliga a pensar en términos de qué necesita cada componente, no de qué tiene el schema.

3. Studio Personalizado

El Sanity Studio es una aplicación React open-source. Podéis:

Añadir componentes de input personalizados que validen en cliente antes de llegar al backend.
Crear vistas previas en tiempo real que rendericen el contenido mientras el editor escribe.
Definir acciones de documento personalizadas (publicar con webhook, generar metadatos SEO, etc.).

Un Studio customizado es un diferenciador real para vuestro equipo editorial.

4. Webhooks para Cachear en Producción

GROQ es rápido, pero no deberíais llamar a la API de Sanity en cada visita de producción. El patrón correcto: GROQ-powered webhooks que disparan un revalidado del cache.

Migraciones Sin Migraciones: El Modelo que Cambia las Reglas

Sanity no requiere migraciones de base de datos. Añadís un campo al schema, y los documentos existentes simplemente tienen ese campo como null hasta que lo rellenáis. No hay ALTER TABLE, no hay downtime, no hay scripts de migración que se ejecuten en producción.

*El trade-off: sacrificáis consistencia de datos por velocidad de iteración. Para sitios impulsados por contenido, es casi siempre la decisión correcta. *

Para sistemas transaccionales, no. Pero Sanity no está diseñado para transacciones. Está diseñado para contenido editorial, y en ese dominio, la capacidad de iterar el schema sin fricción es un superpoder que WordPress, Contentful y Strapi no igualan.

El Framework: El Modelo de 3 Capas para Sanity

Llamadlo El Modelo de Composición Atómica. Tres capas, una dependencia.

Capa de Schemas Atómicos: Tipos pequeños, reutilizables, sin saber quién los va a consumir.
Capa de Proyecciones GROQ: Queries por componente que devuelven exactamente los datos que cada vista necesita.
Capa de Renderizado Contextual: Renderers de Portable Text que transforman el mismo JSON en HTML, texto plano, o nativo según el dispositivo.

Cada capa puede iterarse independientemente. Cambiáis la proyección sin tocar el schema. Cambiáis el renderer sin tocar la query. Cambiáis el schema y los documentos antiguos no se rompen, solo tienen campos vacíos.

La Trampa: No Uses Sanity Como WordPress

Si tratáis Sanity como un CMS que devuelve HTML, estáis usando la herramienta equivocada. Sanity no es un generador de páginas. Es una plataforma de contenido donde vosotros construís las reglas de validación, las relaciones, y los formatos de salida.

*El verdadero poder de Sanity no está en lo que viene configurado. Está en lo que podéis construir vosotros encima. *

GROQ, Portable Text, el Studio personalizable, las suscripciones en tiempo real, los webhooks con firma — cada pieza está diseñada para que montéis vuestro propio CMS, no para que uséis el que otros definieron.

El 90% de los proyectos Sanity ignora esto. El 10% que lo entiende construye sistemas de contenido que son más rápidos, más flexibles, y más fáciles de mantener que cualquier alternativa en el mercado.

*La pregunta no es si Sanity es bueno. La pregunta es si estáis dispuestos a construirlo vosotros. *

Porque Sanity no es un CMS. Es un kit de construcción de CMS. Y el mejor tutorial no os enseña a usarlo — os enseña a decidir qué queréis construir con él.