Cloudinary & Astro

Cloudinary est une plateforme d’images et de vidéos et un gestionnaire de ressources numériques (DAM) sans tête qui vous permet d’héberger des ressources et de les diffuser à partir de leur réseau de diffusion de contenu (CDN).

Lors de la livraison depuis Cloudinary, vous bénéficiez également d’un accès à leur API de transformation, vous donnant la possibilité de modifier vos ressources avec des outils tels que la suppression d’arrière-plan, le recadrage et le redimensionnement dynamiques et l’IA générative.

Utilisation de Cloudinary dans Astro

Cloudinary prend en charge une grande variété de SDK qui peuvent être utilisés en fonction de votre environnement Astro.

Le SDK Astro de Cloudinary fournit des composants Astro natifs, notamment des composants d’image, de vidéo et de téléchargement, ainsi qu’un chargeur de contenu qui peut être utilisé avec les collections de contenu Astro.

Autrement, le SDK Node.js et le SDK JavaScript de Cloudinary peuvent tous les deux être utilisés pour générer des URL pour vos images. Le SDK Node.js peut également effectuer des requêtes auprès de l’API Cloudinary, notamment pour transférer des ressources, interroger des données et exécuter des analyses de contenu.

Prérequis

Un projet Astro existant
Un compte Cloudinary

Installation d’Astro Cloudinary

Installez le SDK Astro de Cloudinary en exécutant la commande appropriée pour votre gestionnaire de paquets :

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

Configuration de votre compte

Créez un nouveau fichier .env à la racine de votre projet et ajoutez vos identifiants Cloudinary :

PUBLIC_CLOUDINARY_CLOUD_NAME="<Votre nom de cloud>"

// Nécessaire uniquement si vous utilisez CldUploadWidget ou cldAssetsLoader
PUBLIC_CLOUDINARY_API_KEY="<Votre clé API>"
CLOUDINARY_API_SECRET="<Votre secret API>"

Utilisation des images Cloudinary

Ajoutez des images dans les composants .astro en transmettant les données d’image (par exemple src, width, alt) au composant <CldImage>. Cela optimisera automatiquement votre image et vous donnera accès à l’API Transformations.

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<ID public>"
  width="<Largeur>"
  height="<Hauteur>"
  alt="<Description>"
/>

Consultez la documentation <CldImage> de Cloudinary pour plus d’informations.

Utilisation des vidéos Cloudinary

Pour ajouter une vidéo à vos composants .astro, ajoutez le composant <CldVideoPlayer> et transmettez les propriétés appropriées. Ce composant optimisera et intégrera automatiquement votre vidéo à l’aide du lecteur vidéo Cloudinary.

---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<ID public>"
  width="<Largeur>"
  height="<Hauteur>"
/>

Consultez la documentation <CldVideoPlayer> de Cloudinary pour plus d’informations.

Activation des transferts vers Cloudinary

Pour activer le transfert de fichiers dans l’interface utilisateur de votre site web ou de votre application, ajoutez le composant <CldUploadWidget> qui intégrera le widget de transfert de Cloudinary.

L’exemple suivant crée un widget pour autoriser les transferts non signés en transmettant un préréglage de transfert non signé :

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Préréglage de transfert>">
  <button>Transfert</button>
</CldUploadWidget>

Pour les transferts signés, vous pouvez trouver un guide et un exemple dans la documentation Astro de Cloudinary.

Consultez la documentation <CldUploadWidget> de Cloudinary pour plus d’informations.

Chargeur de contenu Cloudinary

Le SDK Astro de Cloudinary fournit le chargeur de contenu cldAssetsLoader pour charger les ressources Cloudinary dans les collections de contenu.

Pour charger une collection d’images ou de vidéos, définissez loader: cldAssetsLoader ({}) avec une propriété folder, si nécessaire :

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

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader({
      folder: '<Folder>' // Facultatif, utilise le répertoire racine sinon
    })
  }),
}

Vous pouvez ensuite utiliser les fonctions de requête getCollection() ou getEntry() pour sélectionner une ou plusieurs images ou vidéos de votre collection.

Consultez la documentation cldAssetsLoader de Cloudinary pour plus d’informations.

Générer des URL d’images Cloudinary

Le SDK Astro de Cloudinary fournit un assistant getCldOgImageUrl() pour générer et utiliser des URL pour vos images. Utilisez-le lorsque vous avez besoin d’une URL au lieu d’un composant pour afficher votre image.

Une utilisation courante d’une URL concerne une image Open Graph dans les balises <meta> pour les cartes de réseaux sociaux. Cet assistant, comme les composants, vous donne accès aux transformations Cloudinary pour créer des cartes sociales dynamiques et uniques pour n’importe laquelle de vos pages.

L’exemple suivant montre les balises <meta> nécessaires pour une carte de médias sociaux, en utilisant getCldOgImageUrl() pour générer une image Open Graph :

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

Trouvez des modèles de cartes de réseaux sociaux Cloudinary dans la documentation Cloudinary.

Consultez la documentation getCldOgImageUrl() de Cloudinary pour plus d’informations.

Utilisation de Cloudinary dans Node.js

Pour une gestion, un transfert ou une analyse des ressources plus complexes, vous pouvez utiliser le SDK Node.js de Cloudinary lorsque vous travaillez dans un environnement Astro Node.js.

Installez le SDK Node.js de Cloudinary en exécutant la commande appropriée pour votre gestionnaire de paquets :

npm install cloudinary

pnpm add cloudinary

yarn add cloudinary

Ajoutez les variables d’environnement suivantes dans votre fichier .env :

PUBLIC_CLOUDINARY_CLOUD_NAME="<Votre nom de cloud>"
PUBLIC_CLOUDINARY_API_KEY="<Votre clé API>"
CLOUDINARY_API_SECRET="<Votre secret API>"

Configurez votre compte avec une nouvelle instance Cloudinary en ajoutant le code suivant entre les barrières de code de votre composant 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,
});
---

Cela vous donnera accès à toutes les API Cloudinary pour vous permettre d’interagir avec vos images, vidéos et autres fichiers pris en charge.

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

Découvrez comment transférer des fichiers à l’aide du SDK Node.js de Cloudinary avec Astro Forms.

Ressources officielles

Plus de guides sur les DAM

Cloudinary

Contribuer

Communauté