Function Signature export const cloudinaryStorage : CloudinaryStoragePlugin = ( cloudinaryOptions : CloudinaryStorageOptions ) => ( incomingConfig : Config ) : Config => { // Returns modified Payload config with Cloudinary storage };
Overview The cloudinaryStorage function is the main entry point for the Payload Cloudinary plugin. It returns a Payload plugin function that configures Cloudinary storage for specified collections.
Parameters cloudinaryOptions
CloudinaryStorageOptions
required
Configuration options for Cloudinary storage. See CloudinaryStorageOptions for details. collections
Record<string, CollectionOptions | true>
required
Collections to enable Cloudinary storage for. Use collection slug as key.
Cloudinary API credentials (cloud_name, api_key, api_secret).
folder
string
default: "payload-media"
Folder path in Cloudinary where files will be uploaded.
Whether to enable the plugin.
versioning
CloudinaryVersioningOptions
Versioning configuration options.
Public ID generation options.
Additional custom fields to add to media collections.
Enable PDF thumbnails in the admin UI.
Returns Plugin
(config: Config) => Config
A Payload plugin function that modifies the Payload configuration to use Cloudinary storage.
Behavior When called, cloudinaryStorage:
Returns immediately if enabled is false
Creates a Cloudinary adapter with the provided configuration
Modifies specified collections to:
Disable local storage (disableLocalStorage: true)
Add Cloudinary metadata fields
Add version history fields (if versioning enabled)
Add custom fields (if provided)
Enable PDF thumbnail generation (if enabled)
Returns the modified Payload config
Usage Example import { buildConfig } from 'payload/config' ; import { cloudinaryStorage } from '@payloadcms/plugin-cloudinary' ; export default buildConfig ({ collections: [ { slug: 'media' , upload: true , fields: [ { name: 'alt' , type: 'text' , }, ], }, ] , plugins: [ cloudinaryStorage ({ collections: { media: true , }, config: { cloud_name: process . env . CLOUDINARY_CLOUD_NAME ! , api_key: process . env . CLOUDINARY_API_KEY ! , api_secret: process . env . CLOUDINARY_API_SECRET ! , }, folder: 'my-app/media' , versioning: { enabled: true , storeHistory: true , autoInvalidate: true , }, }), ] , }) ;
PDF Thumbnail Support The plugin automatically generates thumbnails for PDF uploads using Cloudinary’s transformation API:
// Default PDF thumbnail generator (source: index.ts:44-51) const defaultPDFThumbnailGenerator = ( doc : PayloadDocument , cloudName : string , ) : string => { if ( ! doc . cloudinary ?. public_id ) return "" ; const page = doc . cloudinary ?. selected_page || 1 ; return `https://res.cloudinary.com/ ${ cloudName } /image/upload/pg_ ${ page } ,w_300,h_400,c_fill,q_auto,f_jpg/ ${ doc . cloudinary . public_id } .pdf` ; };
See Also 