Sanity.io Headless CMS Tutorial: No es un CMS. Es una Infraestructura de Contenido en Tiempo Real

Sanity.io No es un CMS. Es una Infraestructura de Contenido Mal Etiquetada

El 90% de los que empezáis con Sanity lo tratáis como "otro headless CMS".

Evaluáis precios. Comparáis con Contentful. Migráis desde WordPress. Y luego modeláis el contenido como si fuera SQL.

*Y os perdéis exactamente lo que hace a Sanity revolucionario. *

El error no es técnico. Es conceptual. Sanity no es un panel de administración con API. Es una plataforma de infraestructura de contenido en tiempo real — un Content Lake consultable con GROQ, un formato de texto estructurado (Portable Text) que ni HTML ni Markdown pueden igualar, y un Studio React que tú controlas.

La mayoría lo configura como una base de datos relacional disfrazada de CMS. Y luego se preguntan por qué no notan la diferencia.

Voy a mostraros el framework de 5 pasos para usarlo como toca.

Por Qué el Modelo Mental de "Base de Datos" Te Está Frenando

Si vienes de WordPress o Strapi, piensas en contenido como páginas. Un post tiene un título, un cuerpo HTML, una imagen destacada. Fin.

Sanity no funciona así. Sanity almacena contenido como documentos JSON estructurados en un Content Lake vivo. No hay tablas. No hay filas. No hay JOINs como los conoces.

*El error más común: normalizar los esquemas como si fueras a meterlos en PostgreSQL. *

En SQL, desnormalizar es pecado. En Sanity, desnormalizar es el patrón esperado. Porque GROQ —el lenguaje de consultas de Sanity— te permite atravesar referencias, proyectar arrays y filtrar por tipo de documento en una sola petición.

Lo que en REST serían 3 o 4 endpoints separados, en GROQ es una query.

❌ Enfoque WordPress: Creas un post type "blog", otro "author", y otro "comment". Luego haces 3 peticiones API para montar la página.

✅ Enfoque Sanity: Una query GROQ que en un solo viaje te da el post, el autor (resuelto desde la referencia), y los primeros 3 comentarios. Un viaje de ida y vuelta al servidor.

El Framework de 5 Pasos para Usar Sanity Como Toca

He visto decenas de proyectos con Sanity. Los que funcionan siguen este patrón. Los que fracasan lo ignoran.

Llamadlo El Método del Content Lake: cinco pasos para que Sanity no sea un CMS caro, sino la espina dorsal de tu contenido.

1. Modela como Datos Estructurados, No como Páginas

Tu esquema no debería reflejar cómo se ve una página. Debería reflejar qué es cada cosa.

Cada tipo de documento debe tener un propósito. Persona, producto, categoría — no "página de inicio" como un cajón desastre.

2. Domina GROQ — Es Tu Arma Secreta

GROQ no es GraphQL. No es REST. Es un lenguaje de consultas diseñado para documentos JSON con referencias.

Esto es lo que no puedes hacer con REST tradicional:

Esa query hace en un viaje lo que un backend REST necesitaría 4 endpoints para servir:

Listar posts
Resolver el autor de cada post
Resolver productos relacionados
Resolver comentarios de cada post

Y todo eso con proyecciones selectivas — no traes campos que no necesitas.

*El truco: el operador `->` resuelve referencias en la misma query. * En REST tendrías que hacer un fetch por cada referencia. En GROQ, es sintaxis nativa.

3. Portable Text No es un Editor Rico. Es un Formato Estructural

La mayoría trata Portable Text como "el editor WYSIWYG de Sanity".

Error. Portable Text es un formato JSON de bloques que representa texto enriquecido como un array de objetos tipados. Cada bloque puede ser un párrafo, un encabezado, una lista, o —y aquí está la potencia— un tipo personalizado.

¿Por qué esto es mejor que Markdown o HTML?

Porque el mismo contenido se renderiza de forma distinta en cada plataforma sin parsear HTML con regex. Un tweet embebido en web es un <TweetEmbed />. En mobile, es un TweetView nativo de SwiftUI. En email, es un enlace estático. Los datos son los mismos. El renderizado cambia.

4. Construye un Studio a Tu Medida

El Studio de Sanity no es un admin genérico. Es una aplicación React que despliegas tú y que puedes extender por completo.

Añade componentes de previsualización en vivo. Valida reglas entre documentos. Construye selectores visuales que tu equipo editorial necesita y que ningún CMS de serie ofrece.

Cada customización que haces en el Studio es código React que controlas. El coste: mantenimiento. Cada versión mayor de Sanity puede romper tu Studio. Pero el beneficio —un equipo editorial que no te pide cambios porque ya tiene lo que necesita— lo compensa.

5. Usa el Listener API para Preview en Vivo (y CDN para Producción)

El Content Lake no es una base de datos dormida. Es un sistema en tiempo real con suscripciones mediante Operational Transform (OT) — el mismo mecanismo que usa Google Docs para colaboración simultánea.

*El patrón correcto: * en producción, CDN con cache. En preview, listener con suscripción en tiempo real. Nunca al revés.

Las 3 Objeciones Que Vas a Tener (y Por Qué no Son Mortales)

"GROQ es propietario — vendor lock-in"

GROQ es open source (MIT). Tiene implementaciones en Python, Go, Rust. Y Sanity también soporta GraphQL si prefieres el estándar.

*El riesgo real no es GROQ. Es Portable Text y las customizaciones del Studio. * Migrar desde Sanity requiere exportar documentos JSON y escribir un script que los convierta al formato de destino. No es trivial, pero tampoco es imposible.

"Sanity es overkill para un blog pequeño"

Es cierto. Para una web de 5 páginas con un editor, Sanity es excesivo. Usa flat-file CMS, Markdown, o incluso WordPress.

*Pero si tu proyecto va a crecer —múltiples plataformas, varios editores, contenido reutilizable— la inversión inicial en Sanity se amortiza. * El coste no es económico. Es de aprendizaje. Y ese coste lo pagas una vez.

"Las queries GROQ complejas son lentas"

GROQ con proyecciones profundas puede ser impredecible con miles de documentos. La solución: proyecta solo lo que necesitas. No hagas { ... } que trae todo el documento. Y usa el export de dataset para ETL pesado.

La Línea de Meta

Sanity no es un CMS. Es infrastructure-as-code para contenido.

Si lo tratas como un WordPress con APIs, vas a tener un WordPress caro. Si lo tratas como un backend de contenido con un lenguaje de consultas propio, un formato de texto que se renderiza en cualquier plataforma, y un panel de administración que controlas al 100%, tienes algo que ningún otro CMS te da.

El contenido no son páginas. Son datos estructurados que esperan ser consultados, transformados y renderizados donde haga falta.

Modela así. Consulta con GROQ. Renderiza con Portable Text.

Y deja de llamar "CMS" a lo que es una infraestructura de contenido en tiempo real.