Skip to content

add: guide for delivering remote images #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

add: guide for delivering remote images #600

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7bb39a6
add: guide for delivering remote images
Waqibsk Sep 30, 2025
8e9fe80
add: live example & formatting
Waqibsk Oct 9, 2025
15179f7
fix: url
Waqibsk Oct 9, 2025
43fdeda
fix(typo): remove colon from Watch & Learn
Waqibsk Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions docs/pages/guides/remote-images.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
import Head from 'next/head';
import CodeBlock from '../../components/CodeBlock';
import OgImage from '../../components/OgImage';
import { CldImage } from '../../../next-cloudinary';
import HeaderImage from '../../components/HeaderImage';
import Video from '../../components/Video';


<Head>
<title>Remote Images - Next Cloudinary</title>
<meta name="og:title" content="Delivering Remote Images - Next Cloudinary" />
<meta name="og:url" content={`https://next.cloudinary.dev/guides/remote-images`} />
</Head>

<OgImage title="Remote Images" twitterTitle="Delivering Remote Images" />

# 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](https://cloudinary.com/documentation/fetch_remote_images) 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"`

<HeaderImage>
<CldImage
width="960"
height="600"
src="https://www.wikipedia.org/portal/wikipedia.org/assets/img/[email protected]"
alt="Wikipedia logo"
tint="70:blue:purple"
deliveryType="fetch"
/>
</HeaderImage>

<CodeBlock>
```jsx copy showLineNumbers
import { CldImage } from 'next-cloudinary';

<CldImage
width="960"
height="600"
src="https://www.wikipedia.org/portal/wikipedia.org/assets/img/[email protected]"
deliveryType="fetch"
// Apply transformations like any other Cloudinary image
tint="70:blue:purple"
alt="Wikipedia Logo"
/>
```
</CodeBlock>
This will generate a Cloudinary URL `https://res.cloudinary.com/<your-cloud-name>/image/fetch/f_auto,q_auto,w_960,h_600,e_tint:70:blue:purple/https://www.wikipedia.org/portal/wikipedia.org/assets/img/[email protected]`,
which 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](https://cloudinary.com/documentation/migration#lazy_migration_with_auto_upload).

### Watch & Learn
<Video
title="Upload Images & Videos to Cloudinary Automatically with Auto Upload"
url="https://www.youtube.com/watch?v=LJhsn5A0PFE"
/>



### Implementation with `CldImage`

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

<CodeBlock>
```jsx copy showLineNumbers
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"
/>
```
</CodeBlock>