Communitygithub.com

Patrones de Sanity

Plataforma de contenido estructurado: consultas GROQ, definiciones de esquemas, @sanity/client, Portable Text, manejo de imágenes, listeners en tiempo real, mutaciones, TypeGen

¿Qué es Patrones de Sanity?

Este skill está diseñado para desarrolladores que trabajan con Sanity, una plataforma de contenido estructurado basada en un content lake en tiempo real. Proporciona patrones esenciales como la configuración del cliente con `createClient`, estableciendo siempre `apiVersion` y `useCdn` correctamente. Cubre la escritura de consultas GROQ seguras usando `defineQuery()` y parámetros `$param` para prevenir inyecciones. También incluye la definición de esquemas tipados con `defineType`/`defineField`, el renderizado de texto enriquecido Portable Text con `@portabletext/react`, la generación de URLs de imágenes optimizadas con `@sanity/image-url`, y la realización de mutaciones (crear, parchear, eliminar) con confirmación explícita. Finalmente, detalla cómo configurar TypeGen para obtener tipos TypeScript de extremo a extremo desde los esquemas y las consultas GROQ, así como el uso de listeners en tiempo real y el manejo explícito de borradores. Es compatible con cualquier proyecto que use Sanity como CMS, incluyendo frameworks como Next.js, Remix o SvelteKit.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-cms-sanity

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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/defineField y @sanity/client para la obtención de datos. Siempre establece apiVersion como una cadena con fecha, usa useCdn: true para lecturas públicas, maneja los documentos borrador explícitamente, usa @sanity/image-url para transformaciones de imágenes y renderiza texto enriquecido con @portabletext/react. Genera tipos TypeScript con sanity 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/client con createClient para 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 createClient y la configuración de apiVersion
  • 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:

Mutaciones y 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Caché CDN — Las consultas de lectura pública usan useCdn: true para respuestas almacenadas en el borde de la red. Las mutaciones y lecturas autenticadas usan useCdn: false para datos frescos.
  6. 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 apiVersion en el cliente — Omitir apiVersion usa 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: true con un token — Las respuestas almacenadas en caché CDN ignoran los tokens de autenticación. Las consultas autenticadas deben usar useCdn: false.
  • Acceder a documentos borrador sin un token — Los borradores (documentos drafts.*) requieren un token de API y perspective: '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 en defineQuery() 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-react obsoleto — Reemplazado por @portabletext/react. El paquete antiguo no tiene mantenimiento.

Errores Comunes:

  • Olvidar _key en elementos de array en mutaciones — Cada elemento en un array de Sanity debe tener un campo _key único. Las mutaciones sin _key fallarán.
  • Usar _id con client.create() — create() genera un _id aleatorio. Si especificas _id y el documento existe, da error. Usa createOrReplace() o createIfNotExists() para operaciones idempotentes.
  • No manejar el caso donde [0] devuelve null — Una consulta GROQ que termina con [0] devuelve null si no hay documentos coincidentes. Siempre maneja este caso con una comprobación opcional o un valor por defecto.

</red_flags>

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Skills relacionados