Cloudinary & Astro

Cloudinary es una plataforma de imágenes y vídeos y un Gestor de Activos Digitales (DAM) headless que te permite alojar activos y entregarlos desde su red de distribución de contenido (CDN).

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

Usando Cloudinary en Astro

Cloudinary soporta una amplia variedad de SDKs que pueden ser utilizados dependiendo de tu entorno Astro.

El SDK de Cloudinary para Astro proporciona componentes nativos de Astro, incluyendo componentes de imagen, vídeo y carga, así como un cargador de contenido que puede ser utilizado con las colecciones de contenido de Astro.

Alternativamente, tanto el SDK de Node.js como el SDK de JavaScript de Cloudinary pueden ser utilizados para generar URLs para tus imágenes. El SDK de Node.js puede adicionalmente realizar peticiones a la API de Cloudinary, incluyendo la carga de activos, solicitud de recursos y análisis de contenido.

Prerrequisitos

Un proyecto Astro existente
Una cuenta de Cloudinary

Instalando Astro Cloudinary

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

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

Configurando 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="<Tu Nombre de Nube>"

// Solo necesario si usas CldUploadWidget o cldAssetsLoader
PUBLIC_CLOUDINARY_API_KEY="<Tu Clave API>"
CLOUDINARY_API_SECRET="<Tu Secreto API>"

Usando imágenes de Cloudinary

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

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<ID Público>"
  width="<Ancho>"
  height="<Alto>"
  alt="<Descripción>"
/>

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

Usando vídeos de Cloudinary

Para añadir vídeo a tus componentes .astro, añade el <CldVideoPlayer> y pasa las propiedades apropiadas. Este componente optimizará e incrustará automáticamente tu vídeo usando el Reproductor de Vídeo de Cloudinary.

---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<ID Público>"
  width="<Ancho>"
  height="<Alto>"
/>

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

Habilitando cargas de Cloudinary

Para habilitar la carga de archivos en la interfaz de tu sitio web o aplicación, añade el <CldUploadWidget> que incrustará el Widget de Carga de Cloudinary.

El siguiente ejemplo crea un widget para permitir cargas sin firmar pasando un Preset de Carga sin firmar:

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

Para cargas 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.

Cargador de contenido de Cloudinary

El SDK de Cloudinary para Astro proporciona el cargador de contenido cldAssetsLoader para cargar activos de Cloudinary para colecciones de contenido.

Para cargar una colección de imágenes o vídeos, 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: '<Carpeta>' // Opcional, sin ella carga el directorio raíz
    })
  }),
}

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

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

Generando URLs de imágenes de Cloudinary

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

Un uso común para una URL es para una imagen Open Graph en etiquetas <meta> para tarjetas de redes sociales. Este ayudante, como los componentes, te proporciona acceso a las 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 Open Graph:

---
import { getCldOgImageUrl } from 'astro-cloudinary/helpers';
const ogImageUrl = getCldOgImageUrl({ src: '<ID Público>' });
---
<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="<Título de Twitter>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />

Encuentra Plantillas de Tarjetas de Redes Sociales de Cloudinary en la documentación de Cloudinary.

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

Usando Cloudinary en Node.js

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

Instala el SDK de Node.js de Cloudinary 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="<Tu Nombre de Nube>"
PUBLIC_CLOUDINARY_API_KEY="<Tu Clave API>"
CLOUDINARY_API_SECRET="<Tu Secreto API>"

Configura tu cuenta con una nueva instancia de Cloudinary añadiendo el siguiente código entre las vallas de tu componente 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, vídeos y otros archivos soportados.

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

Aprende cómo cargar archivos usando el SDK de Node.js de Cloudinary con Formularios de Astro.

Recursos Oficiales

Más guías de DAM

Cloudinary

Contribuir Comunidad Patrocinador