payload-storage-cloudinary
v1.3.0
Published
Cloudinary storage adapter for Payload CMS
Maintainers
Readme
Payload Storage Cloudinary Plugin
A powerful Cloudinary storage adapter for Payload CMS v3 that replaces local file storage with Cloudinary's cloud-based solution, providing automatic image optimization, transformations, and global CDN delivery.
Features
- 🚀 Seamless Cloudinary Integration - Direct upload to Cloudinary with automatic URL generation
- 📁 Dynamic Folder Management - Type folder paths dynamically per upload
- 📂 Smart Folder Organization - Auto-create folders and move assets on folder change
- 🎨 Transformation Presets - Define reusable image transformation sets with multi-select support
- 📤 Upload Queue System - Handle large files with progress tracking and chunked uploads
- 🔒 Private Files with Signed URLs - Private files stored as Cloudinary
authenticatedassets, with per-file privacy control - 🌊 Signed Previews - Watermarked or blurred previews of private files, signed so the watermark stays
- 🚫 Smart Re-upload Prevention - Prevents duplicate uploads when updating document fields
- 🌍 Global CDN - Fast content delivery worldwide
- 📱 Responsive Images - Automatic format and quality optimization
Installation
npm install payload-storage-cloudinary
# or
yarn add payload-storage-cloudinary
# or
pnpm add payload-storage-cloudinaryQuick Start
1. Set up environment variables
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret2. Configure the plugin
import { buildConfig } from 'payload'
import { cloudinaryStorage } from 'payload-storage-cloudinary'
export default buildConfig({
// ... your config
plugins: [
cloudinaryStorage({
cloudConfig: {
cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
api_key: process.env.CLOUDINARY_API_KEY,
api_secret: process.env.CLOUDINARY_API_SECRET,
},
collections: {
media: true, // Simple config - just works!
},
}),
],
})3. Create your upload collection
const Media: CollectionConfig = {
slug: 'media',
upload: {
disableLocalStorage: true, // Required - handled by Cloudinary
},
fields: [
{
name: 'alt',
type: 'text',
},
],
}Understanding URL Fields
When you upload a file, the plugin creates several URL fields:
url- The main URL field (always contains the original URL whenpreserveOriginal: true)originalUrl- Direct URL to the original file without any transformationstransformedUrl- URL with selected transformation presets applied (only when presets are selected)thumbnailURL- Always a 150x150 thumbnail for admin UI displaypublicTransformationUrl- Watermark/blur preview stored by versions before 1.3.0. New uploads don't set it; usepreviewUrlpreviewUrl- Combines transformation presets with watermark/blur for private files
URL fields of a private file
On a collection with privateFiles, the plugin builds every URL of a private file when the document is read, after Payload has run the collection's read access. Nothing deliverable is stored in the database, so revoking a reader's access stops them getting new links.
- A reader who may get the original (the collection's
readaccess passes, andcustomAuthCheckpasses if you set one) gets signedauthenticatedURLs inurl,thumbnailURLandtransformedUrl, pluspreviewUrlwhen the document has a preview. - A reader who may only see the preview gets
previewUrl.url,thumbnailURLandtransformedUrlarenull. - A reader with no access to the file gets
nullin every URL field. cloudinaryUrlis never in a response, and neither is theoriginalUrlof a private file. This holds for Local API reads too, where Payload skips field access by default. A public file getsoriginalUrlbuilt at read time, on every Cloudinary collection with or withoutprivateFiles.- Signed URLs don't expire. Treat each one as a bearer link.
The URLs follow the reader of the request. A Local API call without req reads as an anonymous visitor, so pass req to get the URLs your user may see.
Important: When preserveOriginal: true (recommended), transformations are ONLY applied via URL parameters, never during upload. This ensures your original files remain untouched in Cloudinary.
Basic Configuration Examples
Simple Setup
collections: {
media: true, // Just works!
}With Folder Organization
collections: {
media: {
folder: 'website/uploads',
},
}With Transformations
collections: {
media: {
transformations: {
default: {
quality: 'auto',
fetch_format: 'auto',
},
preserveOriginal: true, // Recommended: keeps original file untransformed
},
},
}Advanced Features
Dynamic Folders
Allow users to organize uploads into custom folders:
collections: {
media: {
folder: {
path: 'uploads', // Default folder
enableDynamic: true, // Adds a text field for custom folder paths
fieldName: 'cloudinaryFolder', // Custom field name (optional)
},
},
}Features:
- Users can type paths like
products/2024orblog/images - Folders are automatically created in Cloudinary
- Smart Asset Moving: When you change the folder, the plugin moves the asset instead of re-uploading
- Uses Cloudinary's rename API to preserve the same asset, private (
authenticated) assets included
Transformation Presets with Multi-Select
Users can select multiple transformation presets that will be combined:
import { cloudinaryStorage, commonPresets } from 'payload-storage-cloudinary'
collections: {
media: {
transformations: {
default: {
quality: 'auto',
fetch_format: 'auto',
},
presets: commonPresets, // Built-in presets
enablePresetSelection: true, // Shows multi-select dropdown
preserveOriginal: true, // Recommended
},
},
}Built-in Common Presets:
thumbnail- 150x150 thumb cropcard- 400x400 fill cropbanner- 1200x600 fill cropog-image- 1200x630 Open Graph sizeavatar- 200x200 circular crop with face detectionblur- Blurred preview imagegrayscale- Black and white conversionpixelate- Pixelated effect (20px blocks)
How it works:
- Users can select multiple presets (e.g., "Grayscale" + "Card")
- Transformations are combined and applied via URL only
- The
transformedUrlfield contains the URL with all selected transformations - Original file remains untouched in Cloudinary
Private Files with Signed Previews
Show a watermarked or blurred preview of a private file to readers who may not get the original. The preview is a signed URL of the authenticated original, so editing it to remove the watermark or blur breaks it. A file uploaded before 1.3.0 needs migrating first:
collections: {
media: {
privateFiles: {
enabled: true,
// Who gets the original. Without it, nobody does.
customAuthCheck: (req) => Boolean(req.user),
},
transformations: {
preserveOriginal: true,
publicTransformation: {
enabled: true,
watermark: {
defaultText: 'PREVIEW',
style: {
fontFamily: 'Arial',
fontSize: 50,
color: 'rgb:808080',
opacity: 50,
angle: -45,
},
},
blur: {
effect: 'blur:2000',
quality: 30,
},
},
},
},
}How it works:
- Editors mark files as private using the "Private File" checkbox. A private file uploads as an
authenticatedasset - They check "Enable Preview" on a document
- They choose between "Watermark" or "Blur" transformation type
- A reader who passes
customAuthCheckgets the original URLs andpreviewUrl - Any other reader who may read the document gets only
previewUrl, a signed URL with the selected presets, then the watermark or blur - For an
authenticatedoriginal, which is every private upload from 1.3.0 on and every filemigratePrivateAssetshas moved, Cloudinary answers 401 to a preview URL edited to remove the watermark or blur. A private file uploaded before 1.3.0 stays anuploadasset until migrated, so its original is public and its preview is unsigned. RunmigratePrivateAssets(see Files Uploaded Before 1.3.0) - No separate preview asset is uploaded. The plugin builds
previewUrleach time the document is read
See Previews for Private Files.
Upload Queue for Large Files
Handle large files with progress tracking:
collections: {
media: {
uploadQueue: {
enabled: true,
maxConcurrentUploads: 3,
enableChunkedUploads: true,
largeFileThreshold: 100, // MB - files larger use chunked upload
chunkSize: 20, // MB chunks
},
},
}File Size Limits:
- Files over 100MB automatically use Cloudinary's
upload_largeAPI - Cloudinary limits depend on your plan:
- Free plans: typically 10MB for images, 100MB for videos
- Paid plans: up to 1GB or more
Complete Example
import { buildConfig } from 'payload'
import { cloudinaryStorage, commonPresets } from 'payload-storage-cloudinary'
export default buildConfig({
collections: [
{
slug: 'media',
access: {
// Everyone reads the document, so visitors can get the public preview.
// customAuthCheck below decides who gets the original.
read: () => true,
},
upload: {
disableLocalStorage: true,
},
fields: [
{
name: 'alt',
type: 'text',
},
],
},
],
plugins: [
cloudinaryStorage({
cloudConfig: {
cloud_name: process.env.CLOUDINARY_CLOUD_NAME!,
api_key: process.env.CLOUDINARY_API_KEY!,
api_secret: process.env.CLOUDINARY_API_SECRET!,
},
collections: {
media: {
// Folder configuration
folder: {
path: 'uploads',
enableDynamic: true,
},
// Transformation configuration
transformations: {
default: {
quality: 'auto',
fetch_format: 'auto',
},
presets: commonPresets,
enablePresetSelection: true,
preserveOriginal: true, // Recommended
// Public preview for private files
publicTransformation: {
enabled: true,
watermark: {
defaultText: 'PREVIEW',
style: {
fontFamily: 'Arial',
fontSize: 50,
color: 'rgb:808080',
opacity: 50,
angle: -45,
},
},
blur: {
effect: 'blur:2000',
quality: 30,
},
},
},
// Upload queue for large files
uploadQueue: {
enabled: true,
maxConcurrentUploads: 3,
enableChunkedUploads: true,
largeFileThreshold: 100, // MB
},
// Security: with publicTransformation, only callers who pass
// customAuthCheck get the original. Without it, nobody does.
privateFiles: {
enabled: true,
customAuthCheck: (req) => Boolean(req.user),
},
// Options
resourceType: 'auto',
deleteFromCloudinary: true,
},
},
}),
],
})Frontend Usage
Using the Stored URLs
function ProductImage({ doc }) {
// Use transformedUrl if transformations were selected, otherwise use url
const imageUrl = doc.transformedUrl || doc.url
return (
<img
src={imageUrl}
alt={doc.alt}
width={doc.width}
height={doc.height}
/>
)
}Applying Custom Transformations
Since transformations are applied via URL when preserveOriginal: true, you can easily create variations:
import { getTransformationUrl } from 'payload-storage-cloudinary'
// Create a thumbnail
const thumbnailUrl = getTransformationUrl({
publicId: doc.cloudinaryPublicId,
version: doc.cloudinaryVersion,
customTransformations: {
width: 200,
height: 200,
crop: 'fill',
gravity: 'auto',
}
})
// Create a responsive image
const responsiveUrl = getTransformationUrl({
publicId: doc.cloudinaryPublicId,
version: doc.cloudinaryVersion,
customTransformations: {
width: 'auto',
dpr: 'auto',
quality: 'auto',
fetch_format: 'auto',
}
})getTransformationUrl, generateSignedURL and generateDownloadURL are primitives. They build a URL for any public ID with any transformation and check no access, and for an authenticated asset they sign it. Call them only from trusted server code, never with a public ID or transformations taken from a request. To serve a reader, use the server helpers below or the signed URL endpoints. See Primitives.
Handling Private Files
import { useSignedURL, createPrivateImageComponent } from 'payload-storage-cloudinary/client'
import React from 'react'
// Option 1: Use the hook
function MyPrivateImage({ doc }) {
const { url, loading, error } = useSignedURL('media', doc?.id, {
react: React // Required in Next.js
})
if (loading) return <div>Loading...</div>
if (error) return <div>Error loading image</div>
return url ? <img src={url} alt={doc.alt} /> : null
}
// Option 2: Use the pre-built component
const PrivateImage = createPrivateImageComponent(React)
<PrivateImage
doc={doc}
collection="media"
alt="My private image"
className="w-full h-auto"
/>On the server, the helpers enforce your collection's read access and customAuthCheck. Pass the request, so access resolves against the real reader:
import { getPrivateImageURL } from 'payload-storage-cloudinary'
// null when this reader may not have the file
const url = await getPrivateImageURL(doc, { payload, collection: 'media', req })A call with no req and no user is anonymous. A trusted server job with no reader passes overrideAccess: true. See Server Helpers.
To ask whether a reader may get the original without building a URL, call isAccessAllowedByID({ req, collection, id }). It decides exactly as the endpoints and the helpers do, in every locale, and returns true exactly when getSignedURL returns a URL. The older isAccessAllowed(req, doc, config) is deprecated: it decides only on the document you pass, so never pass it a raw database row on a localized collection. See isAccessAllowedByID.
getSignedURL, getSignedURLs and getServerImageURL sign caller transformations only from the same allowlist as the endpoints (width, height, crop, gravity, quality, fetch_format, dpr, aspect_ratio). Anything else throws, and nothing is signed. Server code that builds a transformation beyond it, such as a watermark overlay, passes overrideTransformationAllowlist: true. Never pass request input with it. See Transformations in the server helpers.
Working with Previews
function ProtectedImage({ doc }) {
if (doc.url) {
// A public file, or a reader who may get the original
return <img src={doc.url} alt={doc.alt} />
}
if (doc.previewUrl) {
// Show the watermarked or blurred preview
return (
<div>
<img src={doc.previewUrl} alt={`${doc.alt} (preview)`} />
<p>This is a preview. Log in to see full quality.</p>
</div>
)
}
// No preview available
return <div>This image requires authentication</div>
}Important Changes in v1.0.7+
No More Re-uploads
The plugin now intelligently prevents re-uploads when you:
- Change transformation presets
- Update alt text or other fields
- Modify folder paths (uses rename instead)
- Toggle privacy settings (renames the asset between
uploadandauthenticatedinstead)
Deletion Protection
The plugin protects against accidental file deletion from Cloudinary:
- During updates: Files are protected when changing transformations, watermarks, or metadata
- During actual deletion: Files are properly removed when you delete the document, private (
authenticated) files included - Why this matters: Prevents a bug in Payload's cloud storage plugin that could delete files during updates
- Logs: You'll see warnings when deletion is prevented during updates
Signed Previews (1.3.0)
A preview of an authenticated original, which is every private upload from 1.3.0 on and every file migratePrivateAssets has moved, is a signed URL:
- Watermarks and blurs are signed in: Editing the URL to remove them breaks the signature, and Cloudinary answers 401
- No public copy: The plugin no longer uploads a separate preview asset. Copies left by older versions stay in Cloudinary until you delete them
- One field:
previewUrlcarries the preview.publicTransformationUrlis deprecated - Original protected: The original is an
authenticatedasset, and only readers who passcustomAuthCheckget it - Files uploaded before 1.3.0: A private file on a
publicTransformationcollection stays anuploadasset until migrated, so its original is public and its preview is unsigned. RunmigratePrivateAssets. See Files Uploaded Before 1.3.0
URL Structure
urlalways contains the original URL (whenpreserveOriginal: true)transformedUrlcontains URL with transformation presetspreviewUrlcombines presets with watermark/blur, signed for anauthenticatedoriginal
Multi-Select Transformations
- Transformation presets now support multiple selections
- Selected transformations are combined in order
- All transformations happen via URL, not during upload
Documentation
- Frontend Transformations Guide - Applying transformations in your app
- Private Images Guide - Complete guide for private files
- Dynamic Folders Guide - Folder organization strategies
- Transformation Presets Guide - Creating and using presets
- Upload Queue Guide - Handling large files
- Public Transformation Guide - Watermarks and blur effects
TypeScript
Full TypeScript support with type definitions included:
import type {
CloudinaryStorageOptions,
CloudinaryCollectionConfig,
TransformationPreset,
SignedURLConfig,
TransformationConfig,
FolderConfig,
} from 'payload-storage-cloudinary'Requirements
- Payload CMS v3.0.0 or higher
- Node.js 18 or higher
- Cloudinary account with API credentials
License
MIT
Support
- GitHub Issues
- Security policy (report vulnerabilities privately, not as issues)
- Documentation
- Payload CMS Discord
- Cloudinary Documentation
Credits
Built with ❤️ for the Payload CMS community.
