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

Sanity.io No Es un CMS. Es un Kit de Construcción de CMS

La mayoría trata Sanity como si fuera WordPress con esteroides.

Crean un schema genérico. Meten contenido. Lo sirven en el frontend. Y ya está.

*El error no es usar Sanity. El error es usarlo como un contenedor de contenido cuando deberías usarlo como un orquestador de datos. *

Sanity.io es un headless CMS, sí. Pero decir eso es como decir que una navaja suiza es un cuchillo. Técnicamente correcto, profundamente incompleto.

Lo que distingue a Sanity de Contentful, Strapi o WordPress no es que sea "headless". Es que te da control a nivel de datos, no a nivel de interfaz.

Tú no configuras Sanity. Tú construyes tu propio CMS con los bloques que Sanity te da. Schemas personalizados. GROQ como query language. Content Lake en tiempo real. Live previews que no son un truco de marketing.

En este tutorial no voy a enseñarte a "instalar Sanity". Vas a aprender a hacer lo que el 90% no hace: *tratar Sanity como una base de datos relacional con superpoderes editoriales, no como un gestor de contenido. *

El Problema: El 90% Usa Sanity como WordPress

Voy a ser directo con vosotros.

Abro proyectos de Sanity cada semana. Y el 90% de los schemas que veo parecen sacados de un tutorial de 2021.

❌ Un campo title y un campo body con Portable Text.

❌ Un slug auto-generado.

❌ Un author como referencia a un documento separado.

❌ Y ya está.

Eso no es un schema de Sanity. Es un molde de WordPress pasado por un API REST.

*Sanity no está diseñado para que copies la estructura de un CMS clásico. Está diseñado para que pienses en términos de relaciones, validación de datos en tiempo real, y composición de contenido. *

El resultado de ese enfoque WordPress es predecible: tu frontend se llena de llamadas anidadas, tu editor tiene que navegar mil pantallas para actualizar un texto, y tu Content Lake acumula documentos huérfanos.

Y luego te preguntas por qué el proyecto es más lento que si hubieras usado un CMS tradicional.

La respuesta es simple: *estás usando Sanity contra su naturaleza. *

El Enfoque Correcto: Sanity Como Base de Datos Editorial

Cambia la mentalidad un segundo.

Deja de pensar en Sanity como un CMS. Piensa en Sanity como una base de datos de documentos con un frontend editorial configurable.

Cada documento de Sanity tiene un _type. Puede tener referencias a otros documentos. Puede tener validación. Puede tener hooks de React para el editor. Puede tener transformaciones de GROQ en tiempo real.

La pregunta no es "qué campos necesita mi página". La pregunta es "qué relaciones de datos necesita mi aplicación".

Y ahora construyes los schemas alrededor de esas relaciones. No al revés.

Voy a mostraroslo con código real.

1. Estructura de Schemas con Sentido

Este es el schema que veis en el 90% de los proyectos:

Funciona. Pero es plano. No hay composición. No hay reutilización. Es un CRUD con referencias.

Ahora mirad esto:

¿Veis la diferencia? No son más campos. Es un cambio de paradigma.

En el primer enfoque, defines cómo se ve el contenido. En el segundo, defines cómo se relaciona y compone.

GROQ: El Query Language que Cambia las Reglas

La mayoría de los tutoriales de Sanity te enseñan GROQ como si fuera GraphQL con sintaxis rara.

No lo es.

*GROQ (Graph-Relational Object Queries) está diseñado para documentos, no para nodos de grafo. *

Mientras que en GraphQL tienes que definir resolvers para cada relación, en GROQ puedes navegar referencias directamente desde el query. Es más cercano a MongoDB aggregation pipeline que a cualquier query language de CMS.

Mirad este ejemplo. Queremos los últimos 10 posts con su autor, las primeras 50 palabras del body, y el count de posts relacionados:

Una sola query. Sin resolvers. Sin N+1. Sin llamadas anidadas.

*Eso es lo que el 90% de los desarrolladores ignora cuando usa Sanity. *

GROQ no es un añadido. Es el motor. Cada vez que haces una query, GROQ la interpreta contra el Content Lake indexado. No contra una base de datos relacional, sino contra un almacén de documentos optimizado para proyecciones.

Y podéis jugar con GROQ directamente desde el Vision plugin del Studio de Sanity. No necesitáis un backend de pruebas. Abrid el Vision tab, pegar el query, ver los resultados. Iterad hasta que la proyección sea exacta.

Montaje Real con Next.js App Router

Vale, teoría suficiente. Vamos a construir algo real.

Voy a asumir que ya tenéis un proyecto de Sanity creado (npm create sanity@latest). Si no, hacedlo ahora. Tarda un minuto.

Paso 1: El Cliente de Sanity en Server Components

En Next.js App Router, los Server Components son el estándar. Esto significa que podéis hacer queries a Sanity directamente desde el servidor, sin exponer tokens al cliente.

Cread este fichero en lib/sanity.ts:

Fijaos en el detalle clave: `next: { revalidate: 60, tags }`.

Eso es Incremental Static Regeneration con tags. Cuando un editor publique cambios en Sanity, podéis usar webhooks para revalidar solo los tags afectados. No todo el sitio. Solo el contenido que cambió.

Paso 2: Query con GROQ desde un Server Component

Sin useEffect. Sin useState. Sin loading spinners. El contenido llega renderizado desde el servidor. SEO listo. Core Web Vitals optimizados.

Paso 3: Webhook de Revalidación

Ahora el truco final. Cuando el editor actualice un post en Sanity, queremos que Next.js revalide solo ese post.

En Sanity Studio, configurad un webhook que apunte a vuestra API Route:

Cuando el editor publique un post, el webhook dispara revalidateTag('post'). Next.js regenera la página en segundo plano. El usuario ve el contenido actualizado sin esperar.

*Eso es un pipeline editorial autónomo. Sin clicks manuales de "regenerar caché". Sin reinicios del servidor. *

El Framework: El Pipeline Editorial Autónomo de 3 Capas

Aquí está el patrón que uso en todos mis proyectos de Sanity. Lo llamo el Pipeline Editorial Autónomo de 3 Capas:

Capa 1 — Schema como contrato de datos

Define relaciones, no campos sueltos
Usa object types reutilizables (SEO, metadatos, bloques)
Validaciones con Reglas de Sanity (máximo N referencias, campos requeridos condicionales)

Capa 2 — GROQ como capa de transformación

Proyecciones exactas (nunca traigas todo el documento)
Expandir referencias en el mismo query (usa ->)
Filtros de arrays y counts para limitar datos al frontend

Capa 3 — Revalidación basada en eventos

Webhook en Sanity apunta a una API Route de Next.js
revalidateTag para regeneración granular por tipo de contenido
ISR con tags para que el renderizado sea siempre fresco sin rebuild total

El resultado: un CMS donde los editores publican y el sitio se actualiza solo. Sin colas de CI/CD. Sin deploys manuales. Sin "espera, que regenero la caché".

Y lo mejor de todo: *has construido el sistema tú mismo. No has instalado un plugin. Has diseñado una arquitectura. *

Lo que la Mayoría Sigue Haciendo Mal

Tres errores que veo semana sí, semana también:

1. No usan GROQ para transformar datos en el servidor

Siguen trayendo documentos completos y filtrando en JavaScript en el cliente. GROQ puede hacer joins, agrupaciones, proyecciones, y ordenaciones. Usadlo.

2. Ignoran los webhooks

El 70% de los proyectos de Sanity que audito no tienen webhooks configurados. El contenido se actualiza cada 60 segundos por ISR. Puede valer para un blog personal, no para un producto en producción.

3. Tratan Portable Text como HTML

Portable Text es un JSON estructurado. Podéis renderizarlo con estilos personalizados, bloques custom, y hasta componentes embebidos. Pero la mayoría lo pasa a HTML genérico con @portabletext/react sin personalizar nada.

*Sanity te da control. Pero el control requiere que te ensucies las manos. *

Tu Primer Schema No Define Contenido. Define Relaciones.

La próxima vez que creéis un proyecto con Sanity, hacedme un favor.

Antes de escribir el primer campo, dibujad las relaciones en una servilleta. Post se relaciona con categoría. Categoría con landing page. Landing page con autor. Autor con equipo.

*Ese grafo de relaciones es tu verdadero schema. Los campos son solo la implementación. *

Sanity.io no es el CMS más fácil de configurar. Nunca lo ha sido.

Es el CMS que te da más control cuando sabes lo que estás haciendo.

Y ahora ya sabéis.