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

El 90% de los Desarrolladores Trata Sanity Como "Otro Headless CMS"

Y están perdiendo lo que realmente importa.

La mayoría pensáis que un headless CMS es una API REST o GraphQL montada sobre una base de datos tradicional. WordPress con un plugin. Strapi con un deploy. Contentful con un plan de pago.

*Sanity es lo contrario. *

Sanity apuesta por que el contenido debe ser completamente estructurado en la capa de almacenamiento — incluso el texto enriquecido. Donde los CMS tradicionales guardan el rich text como un HTML o Markdown opaco, Sanity usa Portable Text: un array de bloques JSON donde cada párrafo, titular, imagen o embed es un objeto independiente con su propio esquema.

¿Qué significa esto en la práctica?

Puedes consultar "todos los titulares de este artículo" o "reemplazar todos los enlaces al dominio X" con una sola consulta GROQ. En WordPress necesitarías exportar toda la base de datos y hacer grep. Literalmente.

El resultado es un cambio fundamental en cómo modelas contenido. La tesis de este artículo es simple: Sanity no es un CMS que usas — es un CMS que construyes. Y la mayoría lo hace al revés.

❌ Lo Que Hace el 90% (y Está Mal)

El error clásico es tratar Sanity como si fuera cualquier otro CMS headless:

*Eso no es construir con Sanity. Eso es usar Sanity como WordPress con esteroides. *

El problema es que cuando tratas Portable Text como una caja negra, estás desperdiciando la razón de ser de la plataforma. El campo body típico almacena todo el contenido del artículo en un único blob JSON. Sí, es más estructurado que HTML, pero sigues sin poder consultar los bloques individuales sin hacer transformaciones post-query.

El 90% de los proyectos que reviso tienen esta pinta:

Ese blockContent típico es un tipo predefinido que incluye párrafos, titulares, imágenes y code blocks. Pero todo mezclado. Si quieres encontrar todos los posts que tienen un "callout" o un embed de YouTube, no puedes — porque no has modelado esos tipos como bloques separados.

✅ La Alternativa Real: Schema-First Rich Text

El enfoque correcto no es "tengo un campo rich text". Es "mi contenido tiene estos bloques específicos".

*El Portable Text no es un editor de texto. Es un sistema de esquemas para contenido enriquecido. *

Mira la diferencia cuando modelas intencionadamente:

Ahora cada bloque es un objeto JSON con su propio esquema. Puedes escribir una query GROQ que encuentre todos los callout en todos los posts. Puedes contar cuántos embed hay. Puedes reemplazar todos los enlaces a un dominio retirado con una sola operación.

*Eso no es posible en ningún otro CMS del mercado sin workarounds. *

GROQ hace esto posible:

Esa query hace en una sola llamada lo que en un CMS tradicional requeriría 5-6 llamadas REST o una petición GraphQL compleja. Filtra posts con autor, ordena por fecha, hace joins con documentos referenciados (author->name), proyecta arrays de referencias (categories[]->title), y cuenta los bloques de tipo callout dentro del rich text.

Portable Text no es una feature menor. Es un cambio fundamental en cómo se almacena y consulta el contenido.

El Framework que Nadie Sigue (pero Debería): El Patrón de 4 Capas para Sanity

He construido varios proyectos con Sanity — desde directorios de gestorías hasta portales legales — y el patrón que funciona siempre es el mismo. Lo llamo El Patrón de las 4 Capas.

Capa 1: Esquemas Intencionales

No uses el tipo blockContent genérico. Define cada bloque que tu contenido necesita:

callout: para destacados y notas importantes
codeBlock: con soporte de sintaxis y lenguaje
embed: para YouTube, Vimeo, tweets
table: para datos tabulares
faq: para preguntas frecuentes dentro del artículo

Cada bloque tiene su propio schema, su propia validación y su propio serializador en el frontend.

Capa 2: Studio a Medida

El Studio de Sanity no es un panel de administración. Es una app React que puedes personalizar.

Necesitas un selector de color para los temas de tus artículos? Instala un date picker de npm y conviértelo en un input custom. Quieres un preview en vivo de cómo queda el artículo en tu frontend? Añade un panel de preview con la misma query que usa tu web.

Cada input custom que construyes es una mejora directa en la experiencia del editor. Y el coste de desarrollo es mínimo comparado con el tiempo que ahorras a tu equipo editorial.

Ese plugin se instala en tu Studio como cualquier dependencia npm. El editor ve un selector visual de color. Tú recibes un string con el hex. Sin hacks. Sin plugins de terceros que se rompen en la siguiente actualización.

Capa 3: GROQ con Joins y Proyecciones

GROQ (Graph-Relational Object Queries) no es un lenguaje de query normal. Es un lenguaje que entiende la estructura del contenido.

Lo que otros CMS hacen con 10 llamadas API, GROQ lo hace en una:

Fíjate en lo que ocurre aquí:

Filtra posts publicados (publishedAt < now())
Ordena por fecha descendente
Pagina con offset ([0...20])
Hace join con el documento del autor
Proyecta solo los títulos de las categorías
Filtra dentro del rich text para devolver solo bloques destacables

Eso es una query. Una. Sin N+1. Sin promesas encadenadas. Sin lógica de hydratación en el frontend.

Capa 4: Preview en Vivo

El último paso — y el que más valor aporta a tu equipo editorial — es el preview en vivo.

Configuras un panel en el Studio que renderiza el contenido usando la misma query y el mismo componente React que usas en producción. El editor ve los cambios en tiempo real: cómo queda el callout, cómo se ve el embed, si el código se renderiza bien.

El editor no necesita saber qué es un serializer. No necesita abrir otra pestaña. Ve el resultado exacto que va a publicar.

¿Y para Proyectos Pequeños? La Objeción Justa

Vale, me dirás: "Sanity es overkill para un blog de 10 artículos."

Tienes razón parcial. GROQ tiene una curva de aprendizaje. Si tu proyecto es un portfolio de 5 páginas, usa Markdown y ya.

*Pero Portable Text escala hacia abajo igual que hacia arriba. *

Un blog de 10 artículos con Portable Text te permite cambiar el diseño completo sin tocar el contenido. Cada bloque es un objeto JSON. Puedes reordenar, filtrar, transformar. Lo que en un CMS tradicional sería una migración, en Sanity es una consulta.

Y el tier gratuito de Sanity aguanta proyectos pequeños sin coste de API. La pregunta no es "¿me merece la pena?". Es "¿quiero poder consultar mi propio contenido como datos estructurados ahora y dentro de 3 años?".

La Objeción del Lock-In: GROQ es Propietario

También me dirás: "GROQ es un lenguaje propietario. Prefiero GraphQL para no atarme."

GROQ es open source con implementaciones en múltiples lenguajes. Sanity también ofrece API GraphQL de serie. Y todo el contenido es accesible mediante HTTP plano y exportable como JSON en cualquier momento.

*El verdadero lock-in no es el lenguaje de query. Es tener tu contenido en HTML opaco que solo entiende WordPress. *

Con Sanity, tu contenido está en JSON estructurado. Puedes migrarlo a cualquier sitio. Puedes consultarlo con cualquier herramienta. La portabilidad es mayor que con cualquier CMS que almacena rich text como cadenas.

Lo Que Construyes Es Un Sistema de Contenido, No un CMS

El error del 90% es pensar que Sanity es un producto cerrado que "se configura".

*Sanity es una plataforma sobre la que construyes tu propio CMS. *

Cada esquema que defines es una decisión de diseño. Cada bloque custom es una feature nueva. Cada input del Studio es una mejora de UX para tu equipo.

Los CMS tradicionales te dan un cajón de sastre: un campo rich text, un campo imagen, un campo fecha. Sanity te da un lienzo en blanco y te dice: "construye el editor que tu contenido necesita".

El resultado es un sistema de contenido hecho a medida. Consultable. Extensible. Que entiende lo que almacena.

*No uses Sanity como si fuera WordPress. No uses Portable Text como si fuera HTML. *

Construye el CMS que tu proyecto merece. Desde el schema. Con bloques reales. Con GROQ que atraviesa documentos. Con un Studio que tus editadores amarán.

Esa es la diferencia entre instalar un CMS y construir un sistema de contenido.

Los que lo entienden — los que dejan de tratar Sanity como "otro headless CMS" — son los que acaban con proyectos que escalan, que migran sin dolor y que consultan su propio contenido como si fuera una base de datos relacional.

*Los demás siguen haciendo queries de texto completo sobre HTML. *