Cloudinary y Astro

Cloudinary es una plataforma de imágenes y video y un gestor de assets digitales headless (DAM) que te permite alojar assets y entregarlos desde su red de distribución de contenido (CDN).

Al entregar desde Cloudinary, además obtienes acceso a su Transformation API, dándote la capacidad de editar tus assets con herramientas como eliminación de fondo, recorte y redimensionamiento dinámico, e IA generativa.

Usar Cloudinary en Astro

Cloudinary soporta una amplia variedad de SDKs que se pueden usar dependiendo de tu entorno de Astro.

El Cloudinary Astro SDK proporciona componentes nativos de Astro, incluyendo componentes de imagen, video y subida, así como un content loader que se puede usar con colecciones de contenido de Astro.

Alternativamente, tanto el Node.js SDK de Cloudinary como el JavaScript SDK se pueden usar para generar URLs para tus imágenes. El Node.js SDK adicionalmente puede hacer solicitudes a la API de Cloudinary incluyendo la subida de assets, solicitud de recursos y ejecución de análisis de contenido.

Requisitos previos

Un proyecto de Astro existente
Una cuenta de Cloudinary

Instalar Astro Cloudinary

Instala el Cloudinary Astro SDK ejecutando el comando apropiado para tu gestor de paquetes:

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

Configurar tu cuenta

Crea un nuevo archivo .env en la raíz de tu proyecto y añade tus credenciales de Cloudinary:

PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"

// Only needed if using CldUploadWidget or cldAssetsLoader
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"

Usar imágenes de Cloudinary

Añade imágenes en componentes .astro pasando datos de imagen (p. ej. src, width, alt) al componente <CldImage>. Esto optimizará automáticamente tu imagen y te dará acceso a la Transformations API.

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
/>

Consulta la documentación de <CldImage> de Cloudinary para más información.

Usar videos de Cloudinary

Para añadir video a tus componentes .astro, añade el <CldVideoPlayer> y pasa las propiedades apropiadas. Este componente optimizará e incrustará automáticamente tu video usando el Cloudinary Video Player.

---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
/>

Consulta la documentación de <CldVideoPlayer> de Cloudinary para más información.

Habilitar subidas a Cloudinary

Para habilitar la subida de archivos en la UI de tu sitio web o app, añade el <CldUploadWidget> que incrustará el Cloudinary Upload Widget.

El siguiente ejemplo crea un widget para permitir subidas sin firma pasando un Upload Preset sin firma:

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Upload Preset>">
  <button>Upload</button>
</CldUploadWidget>

Para subidas firmadas, puedes encontrar una guía y ejemplo en la documentación de Astro Cloudinary.

Consulta la documentación de <CldUploadWidget> de Cloudinary para más información.

Content loader de Cloudinary

El Cloudinary Astro SDK proporciona el content loader cldAssetsLoader para cargar assets de Cloudinary para colecciones de contenido.

Para cargar una colección de imágenes o videos, establece loader: cldAssetsLoader ({}) con una folder, si es necesario:

import { defineCollection } from 'astro:content';
import { cldAssetsLoader } from 'astro-cloudinary/loaders';

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader({
      folder: '<Folder>' // Optional, without loads root directory
    })
  }),
}

Luego puedes usar las funciones de consulta getCollection() o getEntry() para seleccionar una o varias imágenes o videos de tu colección.

Consulta la documentación de cldAssetsLoader de Cloudinary para más información.

Generar URLs de imágenes de Cloudinary

El Astro Cloudinary SDK proporciona un helper getCldOgImageUrl() para generar y usar URLs para tus imágenes. Úsalo cuando necesites una URL en lugar de un componente para mostrar tu imagen.

Un uso común para una URL es para una imagen de Open Graph en etiquetas <meta> para tarjetas de redes sociales. Este helper, al igual que los componentes, te proporciona acceso a transformaciones de Cloudinary para crear tarjetas sociales dinámicas y únicas para cualquiera de tus páginas.

El siguiente ejemplo muestra las etiquetas <meta> necesarias para una tarjeta de redes sociales, usando getCldOgImageUrl() para generar una imagen de Open Graph:

---
import { getCldOgImageUrl } from 'astro-cloudinary/helpers';
const ogImageUrl = getCldOgImageUrl({ src: '<Public ID>' });
---
<meta property="og:image" content={ogImageUrl} />
<meta property="og:image:secure_url" content={ogImageUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="twitter:title" content="<Twitter Title>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />

Encuentra plantillas de Cloudinary Social Media Card en la documentación de Cloudinary.

Consulta la documentación de getCldOgImageUrl() de Cloudinary para más información.

Usar Cloudinary en Node.js

Para una gestión de assets más compleja, subidas o análisis, puedes usar el Cloudinary Node.js SDK cuando trabajes en un entorno Astro Node.js.

Instala el Cloudinary Node.js SDK ejecutando el comando apropiado para tu gestor de paquetes:

npm install cloudinary

pnpm add cloudinary

yarn add cloudinary

Añade las siguientes variables de entorno en tu archivo .env:

PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"

Configura tu cuenta con una nueva instancia de Cloudinary añadiendo el siguiente código entre las vallas de tu componente de Astro:

---
import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: import.meta.env.PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: import.meta.env.PUBLIC_CLOUDINARY_API_KEY,
  api_secret: import.meta.env.CLOUDINARY_API_SECRET,
});
---

Esto te dará acceso a todas las APIs de Cloudinary para permitirte interactuar con tus imágenes, videos y otros archivos soportados.

await cloudinary.uploader.upload('./path/to/file');

Aprende cómo subir archivos usando el Cloudinary Node.js SDK con Astro Forms.

Recursos oficiales

Más guías de medios alojados

Contribuir Comunidad Patrocinar