Cloudinary — Gestión de imágenes

Cloudinary es el CDN de imágenes del proyecto. Sanity no almacena imágenes directamente — guarda únicamente el Public ID de Cloudinary, y el frontend construye la URL en tiempo de ejecución.

Cloudinary (almacén)  →  Public ID  →  Sanity (referencia)  →  Frontend (URL construida)

Credenciales

Las variables de entorno necesarias ya están en apps/web/.env.local:

NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=dzs2mwbyc
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...

El cloud name es el único valor que necesita el frontend para construir URLs públicas.

Subir una imagen

Desde el dashboard de Cloudinary

1. Entra a cloudinary.com  e inicia sesión
2. Ve a Media Library en el menú lateral
3. Navega a la carpeta destino (o crea una nueva, ej. eventos/)
4. Haz clic en Upload → selecciona el archivo
5. Espera a que termine la subida

Convención de carpetas

Organiza las imágenes por contexto para que los Public IDs sean predecibles:

Obtener el Public ID

Después de subir la imagen:

1. Haz clic en la imagen en Media Library
2. En el panel derecho, copia el valor de Public ID

El Public ID incluye la ruta de carpeta:

eventos/yoga-restaurativo-mayo

No incluye la extensión del archivo (.jpg, .webp, etc.) — Cloudinary la maneja automáticamente.

Usar el Public ID en Sanity

En el documento de Evento (o cualquier schema que use imágenes):

1. Abre el documento en Studio
2. Pega el Public ID en el campo imagePublicId
3. Rellena imageAlt con una descripción accesible

imagePublicId: "eventos/yoga-restaurativo-mayo"
imageAlt:      "Participantes en posición de savasana durante el taller de yoga restaurativo"

Cómo el frontend construye la URL

El frontend usa el cloud name + el Public ID para construir URLs de Cloudinary con transformaciones:

function cloudinaryUrl(publicId: string, opts?: { width?: number; quality?: number }) {
  const { width = 800, quality = 80 } = opts ?? {};
  return `https://res.cloudinary.com/dzs2mwbyc/image/upload/w_${width},q_${quality},f_auto/${publicId}`;
}

Parámetros de transformación más usados

Ejemplo de URL completa

https://res.cloudinary.com/dzs2mwbyc/image/upload/w_1200,q_auto,f_auto/eventos/yoga-restaurativo-mayo

Reemplazar una imagen existente

Si necesitas actualizar la imagen de un evento sin cambiar el Public ID:

1. En Media Library, haz clic en la imagen
2. Selecciona Replace → sube la nueva versión
3. Cloudinary invalida el caché automáticamente

Si cambias el Public ID (subes una imagen nueva con otro nombre):

1. Sube la nueva imagen a Cloudinary
2. Copia el nuevo Public ID
3. Actualiza el campo imagePublicId en el documento de Sanity
4. Publica el documento

Limpieza

Cloudinary no elimina imágenes automáticamente. Si borras un evento de Sanity, recuerda eliminar la imagen correspondiente en Media Library para evitar acumular assets huérfanos.