Working with Remote Images

You can leverage Cloudinary's powerful transformation and delivery features even for images not stored in your Cloudinary account.

The CldImage component provides two primary methods for working with remote images:

Method 1: Fetching Remote Images On-the-Fly

The fetch delivery method (opens in a new tab) allows you to use a remote image URL as a source for the CldImage component.

Cloudinary will fetch the image, apply transformations, cache it on the CDN, and deliver it, all without storing it in your Media Library.

This is the simplest way to get started with remote media.

Example:

To use this method, provide the remote image URL to the src prop and set the deliveryType prop to "fetch"

  import { CldImage } from 'next-cloudinary';
 
  <CldImage
    width="1080"
    height="675"
    src="https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2@2x.png"
    deliveryType="fetch"
    // Apply transformations like any other Cloudinary image
    tint="70:blue:purple"
    alt="Wikipedia Logo"
  />

This will generate an <img> with a srcset containing Cloudinary URLs like:

https://res.cloudinary.com/eric-cloudinary/image/fetch/e_tint:70:blue:purple/c_limit,w_1080/f_auto/q_auto/v1/https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2@2x.png?_a=BAVAZGGf0

This URL instructs Cloudinary to retrieve the image from the source URL.

Method 2: Auto-Uploading Remote Images

This method automatically uploads an image from a remote source to your Cloudinary Media Library the first time it's requested.

Use Cases

• Migrating an existing media library from a service like S3 to Cloudinary without downtime
• Permanently storing and managing remote assets in Cloudinary
• Building a media library from a trusted, remote source over time

How to Set Up Auto-Upload Mapping:

1. Navigate to your Cloudinary settings: go to Settings > Upload.
2. Find the Auto upload mapping section: here you will define the mapping.
3. Create a new mapping:

• Target Folder: A virtual folder name to use in your src prop (e.g., s3-images).
• Source URL prefix: Paste the base URL of your remote image storage (e.g., https://my-s3-bucket.s3.amazonaws.com/images/).

4. Save your changes.

For more details, see the official Cloudinary documentation on Lazy Migration with Auto-Upload (opens in a new tab).

Watch & Learn

Implementation with CldImage

Once your mapping is configured, construct the src prop by combining your mapped folder with the remote image's path

 import { CldImage } from 'next-cloudinary';
 
// Remote URL: https://my-s3-bucket.s3.amazonaws.com/images/product-image.jpg
// Mapped Folder: s3-images
 
<CldImage
  width="960"
  height="600"
  src="s3-images/product-image.jpg"
  alt="An image that will be auto-uploaded"
/>