Cloudinary Provider

Full-featured media management with on-the-fly transformations.

Installation


pnpm add @fluxmedia/core @fluxmedia/cloudinary cloudinary

Configuration


import { MediaUploader } from '@fluxmedia/core';
import { CloudinaryProvider } from '@fluxmedia/cloudinary';
 
const uploader = new MediaUploader(
  new CloudinaryProvider({
    cloudName: 'your-cloud-name',
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    secure: true, // Use HTTPS (default: true)
  })
);

Configuration Options

Option	Type	Required	Description
`cloudName`	string	Yes	Your Cloudinary cloud name
`apiKey`	string	Yes	API key from dashboard
`apiSecret`	string	Yes	API secret (keep secure!)
`secure`	boolean	No	Use HTTPS URLs (default: true)

Upload with Transformations


const result = await uploader.upload(file, {
  folder: 'avatars',
  tags: ['user', 'profile'],
  transformation: {
    width: 400,
    height: 400,
    fit: 'cover',
    quality: 80,
    format: 'webp',
  },
});

On-the-fly URL Transformations


// Get URL with transformations
const thumbnail = uploader.getUrl(result.id, {
  width: 150,
  height: 150,
  fit: 'cover',
  format: 'webp',
});
 
// Multiple sizes
const sizes = {
  small: uploader.getUrl(id, { width: 100 }),
  medium: uploader.getUrl(id, { width: 400 }),
  large: uploader.getUrl(id, { width: 800 }),
};

Batch Uploads


const results = await uploader.uploadMultiple(files, {
  folder: 'batch-upload',
  concurrency: 5,
  onBatchProgress: (completed, total) => {
    console.log(`Uploaded ${completed}/${total} files`);
  }
});

Delete Files


// Delete image
await uploader.delete(imageId);
 
// Delete video (specify resource type)
await uploader.delete(videoId, { resourceType: 'video' });
 
// Delete multiple
await uploader.deleteMultiple(['id1', 'id2', 'id3']);

Supported Features


uploader.supports('transformations.resize')   // true
uploader.supports('transformations.crop')     // true
uploader.supports('transformations.format')   // true
uploader.supports('transformations.quality')  // true
uploader.supports('transformations.blur')     // true
uploader.supports('capabilities.aiTagging')   // true
uploader.supports('capabilities.videoProcessing') // true

Native SDK Access

Access the full Cloudinary SDK for advanced operations:


const cloudinary = uploader.provider.native;
 
// Use native Cloudinary SDK features
await cloudinary.uploader.explicit('sample', {
  type: 'upload',
  eager: [{ effect: 'sepia' }]
});
 
// Search API
const results = await cloudinary.search
  .expression('folder:products')
  .execute();

Environment Variables


CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret