تخطَّ إلى المحتوى
This is an unmaintained snapshot of the Astro v4 docs. View the latest docs.

Cloudinary & Astro

هذا المحتوى غير متوفر بلغتك بعد.

Cloudinary is an image and video platform and headless Digital Asset Manager (DAM) that lets you host assets and deliver them from their content delivery network (CDN).

When delivering from Cloudinary, you additionally get access to their Transformation API, giving you the ability to edit your assets with tools like background removal, dynamic cropping and resizing, and generative AI.

Cloudinary supports a wide variety of SDKs that can be used depending on your Astro environment.

The Cloudinary Astro SDK provides native Astro components, including image, video, and upload components, as well as a content loader that can be used with Astro content collections.

Alternatively, both the Cloudinary Node.js SDK and JavaScript SDK can be used to generate URLs for your images. The Node.js SDK can additionally make requests to the Cloudinary API including uploading assets, requesting resources, and running content analysis.

  • An existing Astro project
  • A Cloudinary account

Install the Cloudinary Astro SDK by running the appropriate command for your package manager:

Terminal window
npm install astro-cloudinary

Create a new .env file in the root of your project and add your Cloudinary credentials:

.env
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>"

Add images in .astro components by passing image data (e.g. src, width, alt) to the <CldImage> component. This will automatically optimize your image and give you access to the Transformations API.

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

See Cloudinary’s <CldImage> documentation for more information.

To add video to your .astro components, add the <CldVideoPlayer> and pass the appropriate properties. This component will automatically optimize and embed your video using the Cloudinary Video Player.

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

See Cloudinary’s <CldVideoPlayer> documentation for more information.

To enable file uploading in your website or app’s UI, add the <CldUploadWidget> which will embed the Cloudinary Upload Widget.

The following example creates a widget to allow unsigned uploads by passing an unsigned Upload Preset:

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

For signed uploads, you can find a guide and example on the Astro Cloudinary docs.

See Cloudinary’s <CldUploadWidget> documentation for more information.

The Cloudinary Astro SDK provides the cldAssetsLoader content loader to load Cloudinary assets for content collections.

To load a collection of images or videos, set loader: cldAssetsLoader ({}) with a folder, if required:

config.ts
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
})
}),
}

You can then use the getCollection() or getEntry() query functions to select one or many images or videos from your collection.

See Cloudinary’s cldAssetsLoader documentation for more information.

Generating Cloudinary image URLs

Section titled Generating Cloudinary image URLs

The Astro Cloudinary SDK provides a getCldOgImageUrl() helper for generating and using URLs for your images. Use this when you need a URL instead of a component to display your image.

One common use for a URL is for an Open Graph image in <meta> tags for social media cards. This helper, like the components, provides you access to Cloudinary transformations to create dynamic, unique social cards for any of your pages.

The following example shows the necessary <meta> tags for a social media card, using getCldOgImageUrl() to generate an Open Graph image:

Layout.astro
---
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} />

Find Cloudinary Social Media Card templates on the Cloudinary docs.

See Cloudinary’s getCldOgImageUrl() documentation for more information.

For more complex asset management, uploading, or analysis, you can use the Cloudinary Node.js SDK when working in an Astro Node.js environment.

Install the Cloudinary Node.js SDK by running the appropriate command for your package manager:

Terminal window
npm install cloudinary

Add the following environment variables in your .env file:

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

Configure your account with a new Cloudinary instance by adding the following code between the fences of your Astro component:

Component.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,
});
---

This will give you access to all of the Cloudinary APIs to allow you to interact with your images, videos, and other supported files.

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

Learn how to upload files using the Cloudinary Node.js SDK with Astro Forms.

المزيد من أدلة أنظمة إدارة الأصول الرقمية

ساهم

بماذا تفكّر؟

المجتمع