Hemos estado ejecutando Sanity como nuestro CMS principal en múltiples proyectos de clientes durante más de tres años. Alrededor de la marca de 3.000 posts, dejas de pensar en Sanity en términos de lo que dicen los docs y empiezas a pensar en términos de lo que realmente sobrevive en producción. Este artículo es ese volcado cerebral -- cada decisión de esquema de la que nos arrepentimos, cada consulta GROQ que detuvo una compilación en seco, y cada personalización de Studio que hizo que los editores realmente *quisieran* usar el CMS en lugar de enviarnos documentos de Word.

Este no es una guía de introducción. Si estás aquí, probablemente ya hayas configurado Sanity Studio, creado algunos esquemas y tal vez hayas lanzado un sitio o dos. Lo que quiero compartir son los patrones que solo emergen después de haber tratado con equipos de contenido reales, flujos de trabajo editoriales reales y presupuestos de rendimiento reales a escala.

Tabla de Contenidos

• Diseño de Esquema que Sobrevive Equipos de Contenido Reales
• Rendimiento GROQ a Escala: Lo Que Realmente Importa
• Personalizaciones de Studio que Valen la Inversión
• Migración de Contenido e Integridad de Datos
• Estrategia de Implementación y Entorno
• Monitoreo y Depuración en Producción
• Puntos de Referencia de Rendimiento de Proyectos Reales
• Preguntas Frecuentes

Diseño de Esquema que Sobrevive Equipos de Contenido Reales

El diseño de esquema es donde la mayoría de proyectos de Sanity fallan silenciosamente. No de una manera dramática de explosión y quema -- más bien como una erosión lenta de la confianza editorial. El equipo de contenido comienza a evitar ciertos campos. Crean soluciones alternativas. Seis meses después, la mitad de tu contenido estructurado está realmente metido en un único bloque de texto enriquecido porque el esquema era "demasiado complicado."

Deja de Anidar Excesivamente Objetos

Nuestro mayor error inicial fue crear estructuras de objetos profundamente anidadas. Modelaríamos contenido como un esquema de base de datos -- normalizado, elegante, técnicamente correcto. Una publicación de blog tenía una referencia de author, que tenía un objeto bio, que tenía un array socialLinks de objetos, cada uno con una referencia de platform.

Los editores lo odiaban. Cada vez que necesitaban actualizar el identificador de Twitter de un autor, estaban cinco clics de profundidad. Aquí es lo que hacemos ahora:

// Antes: Sobre-ingeniería
export default defineType({
  name: 'author',
  type: 'document',
  fields: [
    defineField({
      name: 'name',
      type: 'string',
    }),
    defineField({
      name: 'bio',
      type: 'object',
      fields: [
        defineField({
          name: 'content',
          type: 'array',
          of: [{ type: 'block' }],
        }),
        defineField({
          name: 'socialLinks',
          type: 'array',
          of: [
            defineArrayMember({
              type: 'object',
              fields: [
                { name: 'platform', type: 'reference', to: [{ type: 'platform' }] },
                { name: 'url', type: 'url' },
              ],
            }),
          ],
        }),
      ],
    }),
  ],
})

// Después: Plano, amigable para editores
export default defineType({
  name: 'author',
  type: 'document',
  fields: [
    defineField({ name: 'name', type: 'string', validation: (r) => r.required() }),
    defineField({ name: 'bio', type: 'array', of: [{ type: 'block' }] }),
    defineField({ name: 'twitter', type: 'url', title: 'Twitter / X URL' }),
    defineField({ name: 'linkedin', type: 'url', title: 'LinkedIn URL' }),
    defineField({ name: 'github', type: 'url', title: 'GitHub URL' }),
  ],
})

Sí, la versión plana es menos "pura." También se usa correctamente el 100% de las veces. Compensación aceptada.

Usa Grupos de Campos Agresivamente

Una vez que un tipo de documento tiene más de 8-10 campos, los editores comienzan a desplazarse y pierden cosas. Los grupos de campos de Sanity v3 están infravalorados. Los ponemos en cada tipo de documento con más de seis campos:

export default defineType({
  name: 'post',
  type: 'document',
  groups: [
    { name: 'content', title: 'Contenido', default: true },
    { name: 'seo', title: 'SEO' },
    { name: 'settings', title: 'Configuración' },
  ],
  fields: [
    defineField({ name: 'title', type: 'string', group: 'content' }),
    defineField({ name: 'body', type: 'array', of: [{ type: 'block' }], group: 'content' }),
    defineField({ name: 'seoTitle', type: 'string', group: 'seo' }),
    defineField({ name: 'seoDescription', type: 'text', rows: 3, group: 'seo' }),
    defineField({ name: 'publishDate', type: 'datetime', group: 'settings' }),
    defineField({ name: 'featured', type: 'boolean', group: 'settings' }),
  ],
})

Validación que Guía, No Cierra

Aprendimos a pensar en la validación como UX, no como ejecución. Las validaciones duras required() en cada campo significan que los editores no pueden guardar borradores. Los mensajes de validación personalizados que explican por qué algo importa obtienen mucho mejor cumplimiento que los estados de error genéricos:

defineField({
  name: 'excerpt',
  type: 'text',
  rows: 3,
  validation: (rule) =>
    rule
      .max(160)
      .warning('Los extractos de más de 160 caracteres se truncan en resultados de búsqueda y tarjetas sociales.'),
})

Observa que es una warning, no un error. El editor aún puede publicar. Solo saben las consecuencias.

Rendimiento GROQ a Escala: Lo Que Realmente Importa

GROQ es maravilloso hasta que no lo es. Con 500 documentos, todo es rápido. Con 3.000+ documentos con referencias, imágenes y texto portátil, comienzas a notar cosas.

Las Proyecciones No Son Opcionales

El único mayor apalancamiento de rendimiento GROQ es la proyección. Deja de obtener documentos completos cuando solo necesitas tres campos. He visto compilaciones de Next.js pasar de 4 minutos a 90 segundos solo arreglando proyecciones GROQ en llamadas generateStaticParams.

// Lento: obtiene todo incluyendo texto portátil, imágenes, referencias
*[_type == "post"]

// Rápido: solo lo que la página de listado realmente necesita
*[_type == "post"] | order(publishedAt desc) [0...20] {
  _id,
  title,
  slug,
  publishedAt,
  "authorName": author->name,
  "thumbnailUrl": thumbnail.asset->url
}

Esa dereferencia en línea de author->name es crítica. Evita obtener el documento de autor completo. Cuando tienes 3.000 posts cada uno referenciando a uno de 50 autores, la diferencia es medible.

El Problema de Join que Nadie Menciona

La documentación GROQ de Sanity muestra las dereferencias como si fueran gratis. No lo son. Cada -> en una consulta es esencialmente un join. Apila tres o cuatro de ellos en una consulta de lista que devuelve 100 resultados y lo sentirás.

Ahora perfilamos cada consulta GROQ en nuestros proyectos. Aquí está nuestra regla general:

Patrón	Documentos	Tiempo de Respuesta Promedio
Búsqueda simple, sin refs	3.000	~120ms
Un nivel de dereferencia ->	3.000	~250ms
Dos niveles de ->	3.000	~600ms
Array anidado con -> adentro	3.000	~1.200ms+

Estos son números reales del tablero de API de Sanity a mediados de 2025. Tu experiencia variará según el tamaño del documento, pero la tendencia es consistente.

Patrones GROQ que Usamos Constantemente

Obtención condicional para vista previa vs. publicado:

*[_type == "post" && slug.current == $slug && ($preview || !(_id in path('drafts.**')))] [0] {
  ...,
  "author": author-> { name, slug, image },
  "categories": categories[]-> { title, slug }
}

Consultas paginadas con conteo:

{
  "posts": *[_type == "post"] | order(publishedAt desc) [$start...$end] {
    _id, title, slug, publishedAt,
    "authorName": author->name
  },
  "total": count(*[_type == "post"])
}

Posts relacionados sin N+1:

*[_type == "post" && slug.current == $slug][0] {
  ...,
  "related": *[_type == "post" && _id != ^._id && count(categories[@._ref in ^.^.categories[]._ref]) > 0] | order(publishedAt desc) [0...3] {
    title, slug, publishedAt
  }
}

Esa consulta de posts relacionados es densa, pero se ejecuta en el lado del servidor en la infraestructura de Sanity, por lo que generalmente es más rápida que hacer dos viajes de ida y vuelta.

Personalizaciones de Studio que Valen la Inversión

Sanity Studio vainilla está bien para desarrolladores. No está bien para equipos de contenido que envían 20 posts por semana. Aquí está lo que personalizamos en cada proyecto.

Acciones de Documento Personalizadas

La acción de publicación predeterminada no dispara webhooks de manera confiable en todas las configuraciones. Lo envolvemos:

import { useDocumentOperation } from 'sanity'

export function createPublishWithWebhookAction(originalPublishAction) {
  return function PublishWithWebhook(props) {
    const originalResult = originalPublishAction(props)
    return {
      ...originalResult,
      onHandle: async () => {
        await originalResult.onHandle()
        // Dispara revalidación ISR o webhook de implementación
        await fetch('/api/revalidate', {
          method: 'POST',
          body: JSON.stringify({ type: props.type, id: props.id }),
        })
      },
    }
  }
}

Generador de Estructura para Flujos de Trabajo Editoriales

La estructura de escritorio predeterminada muestra cada tipo de documento en una lista plana. Con 15+ tipos de documento, esto es caos. Usamos el Generador de Estructura para crear navegación centrada en la editorial:

import { StructureBuilder } from 'sanity/structure'

export const structure = (S: StructureBuilder) =>
  S.list()
    .title('Contenido')
    .items([
      S.listItem()
        .title('Blog')
        .child(
          S.list()
            .title('Blog')
            .items([
              S.listItem()
                .title('Posts Publicados')
                .child(
                  S.documentList()
                    .title('Publicados')
                    .filter('_type == "post" && !(_id in path("drafts.**"))')
                ),
              S.listItem()
                .title('Borradores')
                .child(
                  S.documentList()
                    .title('Borradores')
                    .filter('_type == "post" && _id in path("drafts.**")')
                ),
              S.listItem()
                .title('Todos los Posts')
                .child(S.documentTypeList('post').title('Todos los Posts')),
            ])
        ),
      S.divider(),
      // ... otros tipos de contenido
    ])

Esto toma 30 minutos para configurar y ahorra a los editores horas de confusión cada semana.

Componentes Personalizados de Texto Portátil

Una cosa que nos golpeó duro: editores pegando contenido de Google Docs en el editor de Texto Portátil. El editor de bloques predeterminado maneja esto bien, pero los tipos de bloques personalizados necesitan serializadores explícitos o aparecen como cajas vacías y los editores entran en pánico.

Registramos componentes personalizados para cada tipo de bloque:

defineArrayMember({
  type: 'object',
  name: 'codeBlock',
  title: 'Bloque de Código',
  fields: [
    defineField({ name: 'code', type: 'text' }),
    defineField({ name: 'language', type: 'string',
      options: { list: ['javascript', 'typescript', 'python', 'bash', 'groq'] }
    }),
  ],
  preview: {
    select: { code: 'code', language: 'language' },
    prepare({ code, language }) {
      return {
        title: `Código (${language || 'plain'})`,
        subtitle: code?.slice(0, 80) + '...',
      }
    },
  },
})

Esa configuración preview es pequeña pero esencial. Sin ella, los editores ven bloques en blanco y no saben qué son.

Migración de Contenido e Integridad de Datos

Hemos hecho cinco migraciones de contenido importantes a Sanity -- desde WordPress, Contentful, Prismic, archivos markdown y un CMS Rails personalizado. Cada una nos enseñó algo doloroso.

Usa las Herramientas de Migración, Pero Confía y Verifica

El paquete @sanity/migrate de Sanity y el sanity documents import de la CLI funcionan bien para casos directos. Para cualquier cosa que implique conversión de texto portátil, escribe scripts personalizados. Siempre.

# Exporta todo para copia de seguridad antes de cualquier migración
sanity dataset export production ./backup-$(date +%Y%m%d).tar.gz

Ejecutamos esto antes de cada migración, cada implementación de esquema e honestamente, cada lunes por la mañana vía cron. Los conjuntos de datos son baratos. El contenido perdido no lo es.

Estrategia de Versionamiento de Esquema

Sanity no fuerza versiones de esquema en la capa de datos. Esto es tanto una característica como un tiro al pie. Los documentos antiguos no se actualizan mágicamente cuando cambias un esquema. Usamos un patrón simple:

defineField({
  name: 'schemaVersion',
  type: 'number',
  hidden: true,
  initialValue: 2,
  readOnly: true,
})

Luego en scripts de migración, podemos consultar *[_type == "post" && schemaVersion < 2] y actualizar por lotes documentos al nuevo formato. Es crudo pero funciona.

Estrategia de Implementación y Entorno

El modelo de conjunto de datos de Sanity admite múltiples entornos, y deberías usarlos desde el primer día -- no después de tu primer incidente de datos de producción.

Nuestra Configuración Estándar

Entorno	Conjunto de Datos	URL de Studio	Propósito
Producción	production	studio.client.com	Edición de contenido en vivo
Staging	staging	staging-studio.client.com	QA de contenido, prueba de esquema
Desarrollo	development	localhost:3333	Desarrollo de esquema

Clonamos producción a staging semanalmente usando sanity dataset copy production staging. Esto mantiene staging realista sin arriesgar datos de producción durante experimentos de esquema.

Para el frontend, nuestros proyectos Next.js development usan variables de entorno para cambiar conjuntos de datos:

const config = {
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET || 'production',
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID,
  apiVersion: '2025-01-01',
  useCdn: process.env.NODE_ENV === 'production',
}

CDN vs. Sin CDN

El CDN de API de Sanity es eventualmente consistente. Para contenido publicado en un sitio de marketing, esto está bien -- el CDN es rápido y la ventana de antigüedad es típicamente menor a 2 segundos. Para contenido de vista previa/borrador, siempre evita el CDN:

const client = sanityClient.withConfig({
  useCdn: false,
  token: process.env.SANITY_PREVIEW_TOKEN,
  perspective: 'previewDrafts',
})

Hemos visto problemas de vista previa que tomaron horas para depurar, solo para darnos cuenta de que el cliente de vista previa estaba golpeando el CDN y mostrando datos obsoletos. Establece useCdn: false para todos los contextos de lectura de vista previa y borrador.

Monitoreo y Depuración en Producción

Perfilado de Consultas GROQ

La consola de administración de Sanity (manage.sanity.io) muestra métricas de uso de API, pero la granularidad no siempre es suficiente. Registramos consultas lentas en el lado frontend:

async function sanityFetch<T>(query: string, params?: Record<string, unknown>): Promise<T> {
  const start = performance.now()
  const result = await client.fetch<T>(query, params)
  const duration = performance.now() - start

  if (duration > 500) {
    console.warn(`Consulta GROQ lenta (${duration.toFixed(0)}ms):`, query.slice(0, 200))
  }

  return result
}

Cualquier cosa mayor a 500ms en producción se investiga. Usualmente es una consulta sin proyección o una dereferencia anidada que se coló en la revisión de código.

Confiabilidad de Webhooks

Los webhooks de Sanity son confiables pero no infalibles. Hemos visto webhooks ocasionalmente perdidos durante actualizaciones de infraestructura de Sanity. Para flujos de trabajo críticos (como disparar reconstrucciones en nuestros proyectos Astro development), implementamos un fallback de sondeo:

// Verifica cambios recientes cada 5 minutos como red de seguridad
const POLL_INTERVAL = 5 * 60 * 1000

setInterval(async () => {
  const lastModified = await client.fetch(
    `*[_type == "post"] | order(_updatedAt desc) [0]._updatedAt`
  )
  if (new Date(lastModified) > lastKnownUpdate) {
    await triggerRebuild()
    lastKnownUpdate = new Date(lastModified)
  }
}, POLL_INTERVAL)

Puntos de Referencia de Rendimiento de Proyectos Reales

Aquí hay números reales de tres proyectos de producción que implementamos en 2024-2025 usando Sanity con frontends headless:

Métrica	Proyecto A (Next.js)	Proyecto B (Astro)	Proyecto C (Next.js)
Documentos totales	3.200	1.800	4.100
Tipos de documento	12	8	18
Respuesta GROQ promedio (CDN)	85ms	72ms	130ms
Respuesta GROQ promedio (sin CDN)	180ms	145ms	290ms
Tiempo de compilación estática completa	3m 20s	1m 45s	6m 10s
Revalidación ISR	1.2s	N/A (estática)	1.8s
Solicitudes de API mensuales	~450K	~180K	~1.2M
Costo de plan Sanity/mes	Growth ($99)	Free	Growth ($99)

El tiempo de compilación más largo del Proyecto C fue enteramente debido al procesamiento de imágenes, no GROQ. Una vez que cambiamos al pipeline de imagen de Sanity con @sanity/image-url y parámetros width/height apropiados, la compilación dejó de descargar imágenes de resolución completa.

Para proyectos de headless CMS development, el precio de Sanity es competitivo. El nivel gratuito es genuinamente utilizable para sitios más pequeños. El plan Growth a $99/mes cubre la mayoría de operaciones editoriales de tamaño medio. Solo comienzas a golpear preocupaciones de costo en volúmenes muy altos de solicitudes de API, y incluso entonces, el uso agresivo de CDN y el almacenamiento en caché inteligente mantienen las cosas razonables.

Cuándo Sanity No es la Opción Correcta

Estaría cometiendo un desservicio si no mencionara los casos en los que hemos desviado a clientes de Sanity:

• Datos altamente relacionales (catálogos de productos con relaciones complejas de variantes) -- una plataforma de comercio dedicada o incluso Postgres tiene más sentido
• Equipos extremadamente no técnicos que necesitan un generador de páginas WYSIWYG -- el Texto Portátil de Sanity es poderoso pero no es Squarespace
• Proyectos con presupuesto limitado con >200K solicitudes de API mensuales -- los costos pueden sorprenderte

Para todo lo demás -- especialmente contenido editorial, sitios de marketing y documentación -- Sanity ha sido nuestro CMS preferido. Si estás evaluando opciones para un proyecto headless, contáctanos y te daremos una evaluación honesta basada en tus necesidades específicas.

Preguntas Frecuentes

¿Cuántos documentos puede manejar Sanity antes de que el rendimiento se degrade? Hemos ejecutado proyectos de producción con más de 4.000 documentos sin degradación significativa. La infraestructura alojada de Sanity maneja recuentos de documentos bien en decenas de miles. El cuello de botella de rendimiento es casi siempre en cómo escribes consultas GROQ -- específicamente, búsquedas sin proyección y cadenas de referencias profundas -- no el recuento de documentos sin procesar.

¿Debo usar GROQ o GraphQL con Sanity? GROQ, a menos que tengas una razón muy específica para usar GraphQL. GROQ es más expresivo para el modelo de documento de Sanity, admite proyecciones de forma más natural y obtiene atención de primera clase del equipo de Sanity. La API de GraphQL se genera automáticamente a partir de tu esquema y funciona bien, pero pierdes algo de la flexibilidad de consulta que hace que Sanity sea poderoso.

¿Cómo manejas la vista previa de borrador con Sanity y Next.js? Usamos el Modo de Borrador de Next.js combinado con la configuración perspective: 'previewDrafts' de Sanity. El cliente de vista previa evita el CDN y usa un token de lectura. El paquete @sanity/preview-kit de Sanity proporciona oyentes en tiempo real que actualizan la página mientras los editores escriben. Requiere algo de configuración pero la experiencia editorial vale la pena.

¿Cuál es la mejor manera de estructurar Texto Portátil para SEO? Mapea tus estilos de bloque de Texto Portátil a HTML semántico apropiado. Usa estilos h2, h3, h4 (no solo "texto grande" o "encabezado"). Añade tipos de bloque personalizados para datos estructurados como secciones de FAQ, pasos de cómo hacerlo y bloques de código. Renderizamos Texto Portátil a HTML usando @portabletext/react con serializadores personalizados que emiten markup compatible con schema.org.

¿Cómo manejas la optimización de imágenes con Sanity? El pipeline de imagen de Sanity es excelente. Usa @sanity/image-url para generar URLs con dimensiones específicas y parámetros de formato. Siempre establece auto=format para permitir que Sanity sirva WebP o AVIF basado en compatibilidad del navegador. Para proyectos de Next.js, usamos el cargador de imagen de Sanity con next/image -- esto te da tanto el CDN de Sanity como la optimización de imagen integrada de Next.js.

¿Puede Sanity manejar contenido localizado/multilingüe a escala? Sí, pero tu diseño de esquema importa enormemente. Usamos el patrón de internacionalización a nivel de documento (documentos separados por locale vinculados por un campo compartido i18nId) en lugar de objetos de traducción a nivel de campo. Con 3.000+ documentos en tres locales, esto mantiene las consultas simples y evita los tamaños de documento masivos que obtienes cuando cada campo contiene un objeto con 5+ claves de idioma.

¿Con qué frecuencia deberías actualizar tu versión de API de Sanity? Fija tu versión de API a una fecha específica (como 2025-01-01) y actualízala trimestralmente después de revisar el registro de cambios. El versionamiento de API de Sanity está basado en fechas y los cambios de ruptura son raros, pero ocurren. Hemos sido golpeados por cambios de comportamiento GROQ no documentados entre versiones de API -- siempre prueba tus consultas críticas después de bumpar la versión.

¿Cuál es el costo de Sanity para un gran equipo editorial? El plan Growth a $99/mes (a mediados de 2025) incluye 1M solicitudes de API, 500K solicitudes de API CDN, y 20 usuarios. Para la mayoría de equipos editoriales que publican 20-50 posts por semana, esto es más que suficiente. El controlador de costo principal es las solicitudes de API -- cada consulta GROQ desde tu frontend cuenta. Usa CDN agresivamente, cachea donde sea posible y evita búsquedas del lado del cliente que se multiplican con el tráfico.