Cloudinary

Image and video management platform with upload, transformation, optimization, and global CDN delivery.

Quick Start

npm install cloudinary

Configuration

import { v2 as cloudinary } from 'cloudinary';

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true
});

Upload

Basic Upload

// From local file
const result = await cloudinary.uploader.upload('./image.jpg', {
  public_id: 'my-image',  // Optional custom ID
  folder: 'products',     // Optional folder
});

console.log(result.secure_url);
// https://res.cloudinary.com/cloud/image/upload/v1234/products/my-image.jpg

// From URL
const result = await cloudinary.uploader.upload(
  'https://example.com/image.jpg',
  { folder: 'external' }
);

// From base64
const result = await cloudinary.uploader.upload(
  'data:image/png;base64,iVBORw0KGgo...',
  { folder: 'uploads' }
);

Upload Options

const result = await cloudinary.uploader.upload('./image.jpg', {
  public_id: 'my-image',
  folder: 'products',

  // Transformations on upload
  transformation: [
    { width: 1000, height: 1000, crop: 'limit' },
    { quality: 'auto', fetch_format: 'auto' }
  ],

  // Eager transformations (pre-generate)
  eager: [
    { width: 200, height: 200, crop: 'thumb', gravity: 'face' },
    { width: 800, crop: 'scale' }
  ],

  // Tags for organization
  tags: ['product', 'shoes'],

  // Metadata
  context: 'caption=Nike Shoes|alt=Running shoes',

  // Overwrite existing
  overwrite: true,
  invalidate: true,

  // Resource type
  resource_type: 'image',  // 'image', 'video', 'raw', 'auto'

  // Access control
  type: 'upload',  // 'upload', 'private', 'authenticated'
});

Upload Large Files

// For files > 100MB
const result = await cloudinary.uploader.upload_large('./large-video.mp4', {
  resource_type: 'video',
  chunk_size: 6000000,  // 6MB chunks
});

URL Transformations

Build URLs with on-the-fly transformations.

// Using cloudinary.url()
const url = cloudinary.url('products/my-image', {
  width: 400,
  height: 300,
  crop: 'fill',
  gravity: 'auto',
  quality: 'auto',
  fetch_format: 'auto',
});
// https://res.cloudinary.com/cloud/image/upload/w_400,h_300,c_fill,g_auto,q_auto,f_auto/products/my-image

// Manual URL construction
const baseUrl = `https://res.cloudinary.com/${cloudName}/image/upload`;
const transformations = 'w_400,h_300,c_fill,g_auto,q_auto,f_auto';
const publicId = 'products/my-image';
const url = `${baseUrl}/${transformations}/${publicId}`;

Transformation Parameters

Resize & Crop

{
  width: 400,
  height: 300,
  crop: 'fill',      // fill, fit, scale, thumb, crop, pad
  gravity: 'auto',   // auto, face, center, north, south, east, west
  aspect_ratio: '16:9',
}

Crop Modes

Mode	Description
fill	Fill dimensions, crop excess
fit	Fit within dimensions, maintain ratio
scale	Scale to dimensions (may distort)
thumb	Thumbnail with smart crop
crop	Crop from specified area
pad	Add padding to fit dimensions
limit	Like fit, but never upscale

Quality & Format

{
  quality: 'auto',        // auto, auto:low, auto:good, auto:best, 1-100
  fetch_format: 'auto',   // auto, webp, avif, jpg, png
}

Effects

{
  effect: 'blur:500',
  effect: 'grayscale',
  effect: 'sepia',
  effect: 'brightness:30',
  effect: 'contrast:50',
  effect: 'saturation:70',
  effect: 'sharpen',
  effect: 'vignette',
  effect: 'art:athena',  // Artistic filters
}

Face Detection

{
  crop: 'thumb',
  gravity: 'face',       // Center on face
  width: 200,
  height: 200,
}

// Multiple faces
{
  crop: 'thumb',
  gravity: 'faces',
  width: 400,
  height: 300,
}

Overlays

// Text overlay
{
  overlay: {
    font_family: 'Arial',
    font_size: 40,
    text: 'Hello World'
  },
  gravity: 'south',
  y: 20,
  color: 'white',
}

// Image overlay (watermark)
{
  overlay: 'logo',
  gravity: 'south_east',
  x: 10,
  y: 10,
  width: 100,
  opacity: 50,
}

Chained Transformations

const url = cloudinary.url('products/shoe', {
  transformation: [
    // First: resize
    { width: 800, height: 600, crop: 'fill' },
    // Then: apply effect
    { effect: 'improve' },
    // Finally: optimize
    { quality: 'auto', fetch_format: 'auto' }
  ]
});

React SDK

npm install @cloudinary/react @cloudinary/url-gen

import { Cloudinary } from '@cloudinary/url-gen';
import { AdvancedImage } from '@cloudinary/react';
import { fill } from '@cloudinary/url-gen/actions/resize';
import { autoGravity } from '@cloudinary/url-gen/qualifiers/gravity';
import { format, quality } from '@cloudinary/url-gen/actions/delivery';
import { auto } from '@cloudinary/url-gen/qualifiers/format';

// Configure
const cld = new Cloudinary({
  cloud: { cloudName: 'your-cloud-name' }
});

function ProductImage({ publicId }) {
  const image = cld
    .image(publicId)
    .resize(fill().width(400).height(300).gravity(autoGravity()))
    .delivery(format(auto()))
    .delivery(quality('auto'));

  return <AdvancedImage cldImg={image} />;
}

With Placeholder & Lazy Loading

import { AdvancedImage, lazyload, placeholder } from '@cloudinary/react';

<AdvancedImage
  cldImg={myImage}
  plugins={[
    lazyload(),
    placeholder({ mode: 'blur' })  // blur, pixelate, vectorize
  ]}
/>

Next.js Integration

With next/image

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'res.cloudinary.com',
      },
    ],
  },
};

import Image from 'next/image';

function CloudinaryImage({ publicId, width, height }) {
  const cloudName = process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME;

  const src = `https://res.cloudinary.com/${cloudName}/image/upload/c_fill,w_${width},h_${height},q_auto,f_auto/${publicId}`;

  return (
    <Image
      src={src}
      alt=""
      width={width}
      height={height}
    />
  );
}

next-cloudinary Package

npm install next-cloudinary

import { CldImage, CldUploadWidget } from 'next-cloudinary';

// Display image
<CldImage
  src="products/shoe"
  width="400"
  height="300"
  crop="fill"
  gravity="auto"
  alt="Product"
/>

// Upload widget
<CldUploadWidget
  uploadPreset="my_preset"
  onUpload={(result) => {
    console.log(result.info.secure_url);
  }}
>
  {({ open }) => (
    <button onClick={() => open()}>Upload</button>
  )}
</CldUploadWidget>

Video Transformations

// Video URL
const videoUrl = cloudinary.url('videos/sample', {
  resource_type: 'video',
  width: 640,
  height: 360,
  crop: 'fill',
  quality: 'auto',
  format: 'mp4',
});

// Thumbnail from video
const thumbnail = cloudinary.url('videos/sample', {
  resource_type: 'video',
  format: 'jpg',
  start_offset: '5',  // 5 seconds in
  width: 400,
  crop: 'fill',
});

// Animated GIF from video
const gif = cloudinary.url('videos/sample', {
  resource_type: 'video',
  format: 'gif',
  start_offset: '2',
  end_offset: '5',
  width: 300,
});

Admin API

// List resources
const resources = await cloudinary.api.resources({
  type: 'upload',
  prefix: 'products/',
  max_results: 100,
});

// Get resource details
const resource = await cloudinary.api.resource('products/shoe');

// Delete resource
await cloudinary.uploader.destroy('products/old-shoe');

// Rename resource
await cloudinary.uploader.rename('old-name', 'new-name');

// Create folder
await cloudinary.api.create_folder('new-folder');

Upload Presets

Configure in Cloudinary dashboard for unsigned uploads.

// Unsigned upload (client-side)
const formData = new FormData();
formData.append('file', file);
formData.append('upload_preset', 'my_preset');

const response = await fetch(
  `https://api.cloudinary.com/v1_1/${cloudName}/image/upload`,
  { method: 'POST', body: formData }
);

const data = await response.json();
console.log(data.secure_url);

Signed Uploads (Secure)

// Server: Generate signature
const timestamp = Math.round(new Date().getTime() / 1000);
const signature = cloudinary.utils.api_sign_request(
  { timestamp, folder: 'uploads' },
  apiSecret
);

// Client: Upload with signature
const formData = new FormData();
formData.append('file', file);
formData.append('api_key', apiKey);
formData.append('timestamp', timestamp);
formData.append('signature', signature);
formData.append('folder', 'uploads');

await fetch(
  `https://api.cloudinary.com/v1_1/${cloudName}/image/upload`,
  { method: 'POST', body: formData }
);

Best Practices

1. Use auto format and quality - f_auto,q_auto for best optimization
2. Generate eager transformations - Pre-generate common sizes
3. Use responsive images - Serve appropriately sized images
4. Enable lazy loading - With blur placeholder
5. Use upload presets - For consistent upload settings
6. Tag and organize - Use folders and tags for management