Cloudinary-Lite

A zero-dependency, ultra-lightweight utility library to handle unsigned client-side uploads and signed server-side deletions with Cloudinary. Works seamlessly in all modern browser environments (React, Angular, Vue, Svelte, Vanilla JS) and Node.js server runtimes.

Installation

Install the package via NPM:

npm install cloudinary-lite

Credential Configuration

1. Client-Side Upload (Public Credentials)

For public client-side uploading, only the public Cloud Name and Upload Preset are required. You should never expose your API Secret on the client side.

Define these in your frontend .env file (e.g. Vite format):

VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name
VITE_CLOUDINARY_UPLOAD_PRESET=your_unsigned_preset

2. Server-Side Deletion (Secret Credentials)

For server-side deletions, you need your private API Key and API Secret to sign the deletion requests securely.

Define these in your server environment variables or .env file:

CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

API Reference

1. Unsigned Upload (Client-Side)

Upload files directly from the browser to Cloudinary.

import { uploadUnsigned } from 'cloudinary-lite';

async function handleFileChange(event) {
  const file = event.target.files[0];
  if (!file) return;

  try {
    const secureUrl = await uploadUnsigned({
      file,
      cloudName: import.meta.env.VITE_CLOUDINARY_CLOUD_NAME,
      uploadPreset: import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET,
      folder: 'alumni/photos', // Optional folder path. Use `null` or `""` if you want to rely on the folder specified in the upload preset.
      resourceType: 'raw' // Optional. The resource type: 'image', 'video', 'raw', or 'auto'. Defaults to 'image'.
    });

    console.log('Uploaded successfully! URL:', secureUrl);
  } catch (error) {
    console.error('Upload failed:', error.message);
  }
}

2. Signed Deletion (Server-Side / Node.js)

Delete assets securely from a backend server. This function dynamically imports Node's native crypto module to securely sign requests.

import { deleteSigned } from 'cloudinary-lite';

async function deleteUserAsset(publicId, resourceType) {
  try {
    const success = await deleteSigned({
      publicId,
      resourceType, // 'image', 'raw', or 'video'
      cloudName: process.env.CLOUDINARY_CLOUD_NAME,
      apiKey: process.env.CLOUDINARY_API_KEY,
      apiSecret: process.env.CLOUDINARY_API_SECRET
    });

    if (success) {
      console.log('Asset deleted successfully');
    } else {
      console.warn('Asset deletion did not return success state');
    }
  } catch (error) {
    console.error('Failed to delete asset:', error.message);
  }
}

3. Parse Cloudinary URLs (Universal Helper)

Extract the public_id and the resource_type from a complete secure URL. Useful when you only store the file URL in the database and need to resolve it for deletion.

import { parseCloudinaryUrl } from 'cloudinary-lite';

const url = 'https://res.cloudinary.com/de3t60fd7/image/upload/v1722513904/alumni/profile-photos/abc123xyz.jpg';
const parsed = parseCloudinaryUrl(url);

console.log(parsed);
// Output:
// {
//   public_id: "alumni/profile-photos/abc123xyz",
//   resource_type: "image"
// }

4. Dynamic URL Scaling & Transformations (Universal Helper)

Generate resized, cropped, or transformed Cloudinary asset URLs on-the-fly.

import { getTransformedUrl, Crop, Quality, Format } from 'cloudinary-lite';

const originalUrl = 'https://res.cloudinary.com/de3t60fd7/image/upload/v1722513904/alumni/profile-photos/abc123xyz.jpg';

// Option A: Pass options object using built-in enums (or plain strings)
const resizedUrl = getTransformedUrl(originalUrl, {
  width: 300,
  height: 300,
  crop: Crop.FILL,
  quality: Quality.AUTO,
  format: Format.AUTO
});
console.log(resizedUrl);
// Output:
// https://res.cloudinary.com/de3t60fd7/image/upload/w_300,h_300,c_fill,q_auto,f_auto/v1722513904/alumni/profile-photos/abc123xyz.jpg

// Option B: Pass raw transformation string
const rawTransformedUrl = getTransformedUrl(originalUrl, 'w_150,h_150,c_thumb,g_face');
console.log(rawTransformedUrl);
// Output:
// https://res.cloudinary.com/de3t60fd7/image/upload/w_150,h_150,c_thumb,g_face/v1722513904/alumni/profile-photos/abc123xyz.jpg

5. Configuration Enums (Helper Constants)

The library exports frozen objects (Crop, Quality, Format) to provide autocomplete, prevent typos, and document standard Cloudinary transformation values.

import { Crop, Quality, Format } from 'cloudinary-lite';

Crop

• Crop.FILL: 'fill'
• Crop.LFILL: 'lfill'
• Crop.FILL_PAD: 'fill_pad'
• Crop.FIT: 'fit'
• Crop.LIMIT: 'limit'
• Crop.MFIT: 'mfit'
• Crop.PAD: 'pad'
• Crop.LPAD: 'lpad'
• Crop.MPAD: 'mpad'
• Crop.SCALE: 'scale'
• Crop.THUMB: 'thumb'
• Crop.CROP: 'crop'

Quality

• Quality.AUTO: 'auto'
• Quality.AUTO_BEST: 'auto:best'
• Quality.AUTO_GOOD: 'auto:good'
• Quality.AUTO_ECO: 'auto:eco'
• Quality.AUTO_LOW: 'auto:low'

Format

• Format.AUTO: 'auto'
• Format.JPG: 'jpg'
• Format.PNG: 'png'
• Format.WEBP: 'webp'
• Format.GIF: 'gif'
• Format.AVIF: 'avif'
• Format.PDF: 'pdf'

License

MIT