¿Qué hace Patrones de Sanity?
Guía rápida: Usa Sanity para la gestión de contenido estructurado con consultas GROQ, esquemas tipados mediante
defineType/defineFieldy@sanity/clientpara la obtención de datos. Siempre estableceapiVersioncomo una cadena con fecha, usauseCdn: truepara lecturas públicas, maneja los documentos borrador explícitamente, usa@sanity/image-urlpara transformaciones de imágenes y renderiza texto enriquecido con@portabletext/react. Genera tipos TypeScript consanity typegen generate.
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo el código debe seguir las convenciones del proyecto en CLAUDE.md (kebab-case, exports nombrados, orden de importaciones,
import type, constantes nombradas)
(SIEMPRE debes establecer apiVersion en createClient con una cadena con fecha como '2025-02-19' — omitirlo usa una API heredada que puede romperse)
(DEBES usar useCdn: true para consultas de lectura pública y useCdn: false cuando uses un token o necesites datos frescos)
(DEBES usar consultas GROQ parametrizadas ($param) para cualquier valor dinámico — nunca interpoles entrada de usuario en cadenas GROQ)
(DEBES manejar los borradores explícitamente — los documentos borrador tienen _id con el prefijo drafts. y no se devuelven por defecto con perspective: 'published')
(DEBES usar defineQuery() de groq y asignar las consultas a variables nombradas para la generación de tipos TypeGen)
</critical_requirements>
Detección automática: Sanity, sanity, @sanity/client, createClient, GROQ, groq, defineType, defineField, defineArrayMember, @sanity/image-url, urlFor, @portabletext/react, PortableText, portable text, block content, sanity.config, sanity.cli, typegen, sanity studio, content lake
Cuándo usarlo:
- Configurar
@sanity/clientconcreateClientpara la obtención de datos - Escribir consultas GROQ (filtros, proyecciones, joins, ordenación, segmentación)
- Definir esquemas de contenido con
defineType,defineField,defineArrayMember - Renderizar Portable Text (contenido de bloques) con
@portabletext/react - Generar URLs de imágenes con
@sanity/image-url(imágenes responsivas, recortes, hotspots) - Realizar mutaciones (crear, parchear, eliminar, transacciones)
- Configurar listeners en tiempo real con
client.listen() - Generar tipos TypeScript con Sanity TypeGen
Patrones clave cubiertos:
- Configuración del cliente con
createClienty la configuración deapiVersion - Lenguaje de consulta GROQ: filtros, proyecciones, ordenación, segmentación, joins, referencias
- Definiciones de esquemas: tipos de documento, tipos de objeto, arrays, referencias, imágenes
- Renderizado de Portable Text con componentes personalizados
- Constructor de URLs de imágenes con imágenes responsivas y transformaciones
- Mutaciones: create, createOrReplace, patch, delete, transacciones
- Listeners en tiempo real mediante
client.listen() - TypeGen para consultas GROQ con seguridad de tipos usando
defineQuery()
Cuándo NO usarlo:
- APIs solo GraphQL (Sanity soporta GROQ principalmente; usa el skill de GraphQL si es necesario)
- Acceso directo a bases de datos (Sanity es un content lake alojado, no una base de datos)
- Plataformas CMS que no sean Sanity (usa el skill dedicado para tu CMS)
Recursos Detallados:
- Para marcos de decisión y tablas de referencia rápida, consulta reference.md
Cliente y GROQ:
- examples/core.md — Configuración del cliente, consultas GROQ, manejo de errores, TypeGen
Esquemas:
- examples/schemas.md — defineType, defineField, tipos de documento, tipos de objeto, referencias, imágenes
Contenido Enriquecido:
- examples/rich-content.md — Renderizado de Portable Text, constructor de URLs de imágenes, imágenes responsivas
Mutaciones y Tiempo Real:
- examples/mutations.md — Crear, parchear, eliminar, transacciones, listeners en tiempo real
Filosofía
Sanity es una plataforma de contenido estructurado construida alrededor de un content lake en tiempo real, GROQ (Graph-Relational Object Queries) como su lenguaje de consulta y Sanity Studio como un entorno de edición personalizable.
Principios fundamentales:
- Contenido estructurado — El contenido se define mediante esquemas (
defineType,defineField) que describen la forma, validación y UI editorial. Los esquemas son código, no archivos de configuración. - Consultas GROQ primero — GROQ te permite filtrar, proyectar, unir y remodelar datos en una sola consulta. A diferencia de REST o GraphQL, las consultas GROQ devuelven exactamente la forma que defines en la proyección.
- El contenido como datos — El texto enriquecido se almacena como Portable Text (una especificación basada en JSON), lo que permite renderizarlo en cualquier framework frontend sin dependencia del proveedor.
- Versionado de API — Cada cliente debe especificar una cadena de fecha
apiVersion. Esto fija tu código a un comportamiento específico de la API, evitando que los cambios disruptivos afecten a producción. - Caché CDN — Las consultas de lectura pública usan
useCdn: truepara respuestas almacenadas en el borde de la red. Las mutaciones y lecturas autenticadas usanuseCdn: falsepara datos frescos. - Generación de tipos — Sanity TypeGen genera tipos TypeScript tanto de tus esquemas como de las consultas GROQ, permitiendo una seguridad de tipos de extremo a extremo desde el modelo de contenido hasta el frontend.
Cuándo usar Sanity:
- Sitios web y aplicaciones impulsadas por contenido (blogs, sitios de marketing, documentación)
- Proyectos que necesitan edición colaborativa en tiempo real en un estudio personalizable
- Entrega de contenido multicanal (web, móvil, IoT) desde una única fuente de contenido
- Equipos que desean consultas de contenido con seguridad de tipos usando GROQ y TypeGen
Cuándo NO usarlo:
- Datos transaccionales que requieren garantías ACID (usa una base de datos)
- Contenido generado por usuarios a gran escala (Sanity está optimizado para contenido editorial)
- Proyectos que necesitan un CMS autoalojado (el content lake de Sanity está alojado, aunque el Studio es de código abierto)
Patrones Principales
Patrón 1: Configuración del Cliente con createClient
Configura @sanity/client con el ID del proyecto, dataset, versión de API y preferencia de CDN. Siempre establece apiVersion a una cadena con fecha y useCdn explícitamente.
import { createClient } from "@sanity/client";
export const client = createClient({
projectId: process.env.SANITY_PROJECT_ID!,
dataset: process.env.SANITY_DATASET!,
apiVersion: "2025-02-19", // Fijar a una fecha de versión de API específica
useCdn: true, // true para lecturas públicas, false para datos autenticados/frescos
});
Para la configuración de cliente dual (público + vista previa con token), consulta examples/core.md.
Patrón 2: Consultas GROQ con Filtros y Proyecciones
Las consultas GROQ combinan filtros, proyecciones, ordenación y segmentación. Siempre usa defineQuery() para TypeGen y $param para valores dinámicos.
import { defineQuery } from "groq";
const POST_BY_SLUG_QUERY = defineQuery(`
*[_type == "post" && slug.current == $slug][0]{
_id, title, body, "author": author->{name, image}
}
`);
const post = await client.fetch(POST_BY_SLUG_QUERY, { slug: "my-post" });
Nunca interpoles entrada de usuario en cadenas GROQ -- siempre usa parámetros $param para prevenir la inyección GROQ. Para consultas avanzadas (consultas combinadas, proyecciones condicionales), consulta examples/core.md.
Patrón 3: Definiciones de Esquemas con defineType y defineField
Define la estructura del contenido con defineType, defineField y defineArrayMember de "sanity" para seguridad de tipos y UI de Studio.
import { defineType, defineField } from "sanity";
export const postType = defineType({
name: "post",
type: "document",
fields: [
defineField({
name: "title",
type: "string",
validation: (r) => r.required(),
}),
defineField({ name: "slug", type: "slug", options: { source: "title" } }),
],
});
Para esquemas completos (imágenes con hotspot, arrays, referencias, vistas previas, tipos de objeto), consulta examples/schemas.md.
Patrón 4: Renderizado de Portable Text
Renderiza contenido de bloques con @portabletext/react. Define PortableTextComponents personalizados para bloques no estándar (imágenes, código) y marcas (enlaces, resaltados).
import { PortableText } from "@portabletext/react";
<PortableText value={body} components={components} />;
No uses el paquete obsoleto @sanity/block-content-to-react. Para ejemplos completos de componentes, consulta examples/rich-content.md.
Patrón 5: Constructor de URLs de Imágenes
Usa @sanity/image-url para generar URLs de imágenes optimizadas y responsivas con soporte de recorte y hotspot.
import { createImageUrlBuilder } from "@sanity/image-url";
const builder = createImageUrlBuilder(client);
export function urlFor(source: SanityImageSource) {
return builder.image(source);
}
// Uso: urlFor(image).width(800).auto("format").url()
Para patrones de srcSet responsivo y transformaciones de imágenes, consulta examples/rich-content.md.
Patrón 6: Mutaciones (Crear, Parchear, Eliminar)
Usa los métodos de @sanity/client para las mutaciones de documentos. Siempre llama a .commit() en parches y transacciones.
await client.create({ _type: "post", title: "New Post" });
await client.patch("post-123").set({ title: "Updated" }).commit();
await client.delete("post-123");
Para createOrReplace, createIfNotExists, transacciones, inserciones en arrays y opciones de visibilidad, consulta examples/mutations.md.
Patrón 7: Listeners en Tiempo Real
Suscríbete a los cambios de documentos con client.listen(). El listener solo usa la parte de filtro de GROQ -- las proyecciones y la ordenación se ignoran.
const subscription = client.listen(`*[_type == "post"]`).subscribe({
next: (update) => {
/* update.transition: 'update' | 'appear' | 'disappear' */
},
error: (err) => console.error(err),
});
subscription.unsubscribe(); // Limpiar cuando termine
Para frontends de producción, evalúa la nueva API de Live Content como una alternativa más simple. Para opciones de listener y advertencias, consulta examples/mutations.md.
Patrón 8: TypeGen para GROQ con Seguridad de Tipos
Configura TypeGen en sanity.cli.ts con overloadClientMethods: true para resultados tipados de client.fetch. Usa defineQuery() de "groq" para que TypeGen pueda descubrir las consultas.
// sanity.cli.ts — establecer typegen.overloadClientMethods: true
// queries/post-queries.ts — envolver consultas con defineQuery()
// sanity.types.ts — tipos de resultado generados automáticamente
const posts = await client.fetch(allPostsQuery); // Resultado tipado
Las cadenas de consulta en línea sin defineQuery() producen resultados sin tipo (any). Para la configuración completa de TypeGen y flujo de trabajo, consulta examples/core.md.
<decision_framework>
Marco de Decisión
useCdn: true vs false
¿Los datos son públicos y no personalizados?
├─ SÍ → useCdn: true (almacenado en el borde de la red, rápido)
└─ NO →
├─ ¿Usando un token para lecturas autenticadas? → useCdn: false
├─ ¿Necesitas datos frescos en tiempo real (vista previa)? → useCdn: false
└─ ¿Realizando mutaciones? → useCdn: false
Manejo de Borradores
¿Necesitas documentos borrador?
├─ SÍ → Usa perspective: 'previewDrafts' (requiere token)
├─ NO → Usa perspective: 'published' (por defecto desde API v2025-02-19)
└─ ¿Mixto (alternar modo vista previa)?
└─ Crea dos clientes: uno público (useCdn: true), uno de vista previa (token + useCdn: false)
Forma de Retorno de la Consulta GROQ
¿Cuántos documentos esperas?
├─ Uno (por ID, slug, singleton) → Agrega [0] al final (devuelve objeto o null)
├─ Muchos (lista, feed) → Sin sufijo de segmentación (devuelve array)
└─ Paginado → Agrega segmento [inicio...fin]
Manejo de Imágenes
¿Cómo deben entregarse las imágenes?
├─ Tamaño fijo (miniaturas, avatares) → urlFor(img).width(W).height(H).url()
├─ Responsivo (imágenes de artículos) → srcSet con múltiples anchos
├─ Optimización de formato → .auto('format') para WebP/AVIF
└─ Recortado a relación de aspecto → .width(W).height(H).fit('crop')
Selección del Método de Mutación
¿Qué operación necesitas?
├─ Crear nuevo documento → client.create()
├─ Crear o reemplazar completamente → client.createOrReplace() (para singletons)
├─ Crear solo si no existe → client.createIfNotExists()
├─ Actualizar campos específicos → client.patch(id).set({...}).commit()
├─ Eliminar campos → client.patch(id).unset([...]).commit()
├─ Múltiples cambios relacionados → client.transaction()...commit()
└─ Eliminar documento → client.delete(id)
</decision_framework>
<red_flags>
BANDERAS ROJAS
Problemas de Alta Prioridad:
- Falta
apiVersionen el cliente — OmitirapiVersionusa un comportamiento de API heredado que puede cambiar sin previo aviso. Siempre fija una cadena con fecha. - Interpolación de cadenas en consultas GROQ — Interpolar entrada de usuario en cadenas GROQ permite la inyección GROQ. Siempre usa parámetros
$param. - Usar
useCdn: truecon un token — Las respuestas almacenadas en caché CDN ignoran los tokens de autenticación. Las consultas autenticadas deben usaruseCdn: false. - Acceder a documentos borrador sin un token — Los borradores (documentos
drafts.*) requieren un token de API yperspective: 'previewDrafts'. Sin un token, los borradores son invisibles.
Problemas de Prioridad Media:
- Obtener todos los campos con
{...}cuando solo se necesitan unos pocos — La sobrecarga de obtención desperdicia ancho de banda y la eficiencia de la caché CDN. Proyecta solo los campos que necesitas. - Falta
.commit()en parches —client.patch(id).set({...})sin.commit()no hace nada — la mutación nunca se envía. - No usar
defineQuery()para consultas GROQ — TypeGen no puede generar tipos para consultas que no están envueltas endefineQuery()o asignadas a variables nombradas. - ID de proyecto o dataset hardcodeados — Usa variables de entorno; los valores hardcodeados impiden el cambio de entorno y filtran detalles del proyecto.
- Usar
@sanity/block-content-to-reactobsoleto — Reemplazado por@portabletext/react. El paquete antiguo no tiene mantenimiento.
Errores Comunes:
- Olvidar
_keyen elementos de array en mutaciones — Cada elemento en un array de Sanity debe tener un campo_keyúnico. Las mutaciones sin_keyfallarán. - Usar
_idconclient.create()—create()genera un_idaleatorio. Si especificas_idy el documento existe, da error. UsacreateOrReplace()ocreateIfNotExists()para operaciones idempotentes. - No manejar el caso donde
[0]devuelvenull— Una consulta GROQ que termina con[0]devuelvenullsi no hay documentos coincidentes. Siempre maneja este caso con una comprobación opcional o un valor por defecto.
</red_flags>