Integrating Cloudinary with Astro

Astro is a JavaScript-based web framework that helps developers build fast, content-driven websites.

Cloudinary can help Astro developers build richer, performance-first visual experiences by leveraging automatic optimization, transformations like dynamic cropping and resizing, and media management tools like uploading with our drop-in Upload Widget.

Using Cloudinary with Astro

There are multiple options for integrating Cloudinary with an Astro app.

Astro Cloudinary

Astro Cloudinary is the recommended way for using Cloudinary in an Astro app. It comes with out-of-the-box image and video optimization along with Cloudinary’s transformation API allowing you to customize your images on-the-fly.

Important: Astro Cloudinary is developed, tested and maintained by the Cloudinary Developer Experience Team and broader developer community. Bug fixes and feature requests should be submitted in the relevant repository.

The CldImage component wraps the Unpic Astro Image component, providing you with a state-of-the-art base image component, extended with Cloudinary tech.

This includes features beyond automatic optimization like dynamic cropping and resizing, background removal, generative AI, image and text overlays, and a lot more.

For basic usage, first install the package with:

npm install astro-cloudinary

Next, add an environment variable to your .env file configuring your Cloudinary cloud name:

CLOUDINARY_CLOUD_NAME="Your Cloudinary Cloud Name".

Need help finding your credentials? Learn more.

To use the CldImage component, pass in your image’s Public ID along with its dimensions and some alternative text:

”<CldImage
  src="<Public ID>"
  width="600"
  height="600"
  alt=”<Description>”
/>

To use the CldVideoPlayer component, similarly pass in your video’s Public ID and dimensions:

<CldVideoPlayer
  src="<Public ID>"
  width="1920"
  height="1080"
/>

To source Cloudinary images and videos into an Astro project, use the cldAssetLoader as part of Astro’s Content Layer:

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

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader()
  }),
}

Where then you can access the assets using the getCollection function:

import { getCollection } from 'astro:content';
const assets = await getCollection('assets');

Learn more about all of the features at: https://astro.cloudinary.dev/

Using the Astro Image component

The Astro Image component supports loading external providers like Cloudinary. To use Cloudinary URLs with Astro Image, you simply need to authorize Cloudinary URLs as a remote image source.

For example, to configure Cloudinary as a remote source: 

export default defineConfig({
  image: {
    domains: ["res.cloudinary.com"],
  }
});

For more information on how to use the Astro Image component with Cloudinary, head over to the Astro docs.

Building Image & Video URLs with the Cloudinary JavaScript SDK

The JS URL Gen SDK allows developers to integrate with Cloudinary in any JavaScript-based applications.

You can use the JavaScript SDK to generate image and video URLs along with any transformations you want.

To get started, first install the JavaScript SDK with:

npm install @cloudinary/url-gen

Set up a new instance of Cloudinary with your cloud’s configuration:

import { Cloudinary } from '@cloudinary/url-gen';

const cld = new Cloudinary({
  cloud: {
    cloudName: '<Your Cloud Name>'
  }
});

Then use one of the available methods to generate your asset URL such as:

const myImage = cld.image('<Public ID>').format('auto').quality('auto').toURL().

Which will build an image URL that will use automatic optimization.

Learn more over on the Cloudinary Docs.

Uploading & Managing Media Assets with the Cloudinary Node.js SDK

When working in an Astro project, you have access to a server environment that allows you to work in Node.js.

Inside Node, you can take advantage of the Cloudinary Node.js SDK to upload files and interact with other Cloudinary APIs like search and administration.

To get started, first install the Cloudinary Node.js SDK:

npm install cloudinary

Configure the package and your Cloudinary account:

import { v2 as cloudinary } from 'cloudinary';

cloudinary.config({
  cloud_name: '<Your Cloud Name>',
  api_key: '<Your API Key>', // Store in .env
  api_secret: '<Your API Secret'>, // Store in .env
});

const result = await cloudinary.uploader.upload('/path/to/image');

Note: Avoid storing your credentials directly in the code to avoid compromising your account. Use environment variables instead to securely use your API key, API secret, and optionally your Cloud Name within your application.

Learn more over on the Cloudinary Docs.

More Resources

Learn more about how to use Cloudinary with Astro:

• How to Optimize & Dynamically Resize Images in Astro with Cloudinary
• Image Optimization in Astro with Cloudinary
• Astro Code Examples