Types

CloudinaryStorageOptions

Main configuration options for the Cloudinary storage plugin.

export type CloudinaryStorageOptions = {
  collections: Partial<
    Record<UploadCollectionSlug, Omit<CollectionOptions, "adapter"> | true>
  >;
  config: CloudinaryConfig;
  folder?: string;
  disableLocalStorage?: boolean;
  enabled?: boolean;
  versioning?: CloudinaryVersioningOptions;
  publicID?: PublicIDOptions;
  supportDynamicFolderMode?: boolean;
  customFields?: Field[];
  enablePDFThumbnails?: boolean;
};

Properties

collections

Record<string, CollectionOptions | true>

required

Collections to apply the Cloudinary adapter to. Key is the collection slug, value is either true or custom collection options.

collections: {
  media: true,
  images: { disablePayloadAccessControl: true },
}

config

CloudinaryConfig

required

Cloudinary API credentials. See CloudinaryConfig.

folder

string

default:"payload-media"

Folder path in Cloudinary where files will be uploaded.

disableLocalStorage

boolean

default:true

Whether to disable local storage. Plugin automatically sets this to true for configured collections.

enabled

boolean

default:true

Whether to enable the plugin. Set to false to disable without removing the plugin.

versioning

CloudinaryVersioningOptions

Versioning configuration. See CloudinaryVersioningOptions.

publicID

PublicIDOptions

Public ID generation options. See PublicIDOptions.

supportDynamicFolderMode

boolean

default:true

Support for Dynamic Folder Mode. Uses asset_folder parameter in upload to ensure correct folder display in Cloudinary Media Library.

customFields

Field[]

Additional custom Payload fields to add to media collections. These are merged with default Cloudinary fields.

customFields: [
  { name: 'alt', type: 'text' },
  { name: 'caption', type: 'textarea' },
]

enablePDFThumbnails

boolean

default:true

Enable automatic PDF thumbnail generation in the admin UI.

CloudinaryConfig

Cloudinary API credentials configuration.

export type CloudinaryConfig = {
  cloud_name: string;
  api_key: string;
  api_secret: string;
};

Properties

cloud_name

string

required

Your Cloudinary cloud name. Find this in your Cloudinary dashboard.

api_key

string

required

Your Cloudinary API key.

api_secret

string

required

Your Cloudinary API secret. Keep this secure and use environment variables.

Example

config: {
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME!,
  api_key: process.env.CLOUDINARY_API_KEY!,
  api_secret: process.env.CLOUDINARY_API_SECRET!,
}

CloudinaryMetadata

Metadata stored in Payload documents for Cloudinary assets.

export type CloudinaryMetadata = {
  public_id: string;
  resource_type: string;
  format: string;
  secure_url: string;
  bytes: number;
  created_at: string;
  duration?: number;
  width?: number;
  height?: number;
  eager?: any[];
  version?: string;
  version_id?: string;
  pages?: number;
  selected_page?: number;
  thumbnail_url?: string;
  type?: string;
};

Properties

public_id

string

required

The public identifier for the asset in Cloudinary.

resource_type

string

required

Type of resource: "image", "video", "raw", or "auto".

format

string

required

File format (e.g., "jpg", "png", "pdf", "mp4").

secure_url

string

required

HTTPS URL to access the asset.

bytes

number

required

File size in bytes.

created_at

string

required

ISO 8601 timestamp of when the asset was created.

duration

number

Duration in seconds (for video and audio files).

width

number

Width in pixels (for images and videos).

height

number

Height in pixels (for images and videos).

eager

any[]

Eager transformations applied to the asset.

version

string

Cloudinary version identifier.

version_id

string

Unique version ID (when versioning is enabled).

pages

number

Number of pages (for PDF files).

selected_page

number

Selected page for thumbnail generation (for PDF files).

thumbnail_url

string

Direct URL to the asset thumbnail.

type

string

Upload type: "upload", "private", or "authenticated".

CloudinaryVersioningOptions

Configuration for Cloudinary versioning features.

export type CloudinaryVersioningOptions = {
  enabled?: boolean;
  autoInvalidate?: boolean;
  storeHistory?: boolean;
};

Properties

enabled

boolean

default:false

Whether to enable versioning support.

autoInvalidate

boolean

default:false

Whether to automatically invalidate old versions in CDN cache.

storeHistory

boolean

default:false

Whether to store version history in Payload CMS. When true, adds a versions field to track all versions.

Example

versioning: {
  enabled: true,
  storeHistory: true,
  autoInvalidate: true,
}

PublicIDOptions

Options for customizing Cloudinary public ID generation.

export type PublicIDOptions = {
  enabled?: boolean;
  useFilename?: boolean;
  uniqueFilename?: boolean;
  generatePublicID?: (
    filename: string,
    prefix?: string,
    folder?: string,
  ) => string;
};

Properties

enabled

boolean

default:true

Whether to enable custom public ID generation.

useFilename

boolean

default:true

Whether to use the original filename as part of the public ID.

uniqueFilename

boolean

default:true

Whether to ensure unique filenames by adding a random suffix.

generatePublicID

function

Custom function to generate a public ID. If provided, overrides useFilename and uniqueFilename.Parameters:

filename (string): The original filename
prefix (string | undefined): The file prefix (if any)
folder (string | undefined): The base folder

Returns: string - The public ID to use

generatePublicID: (filename, prefix, folder) => {
  const timestamp = Date.now();
  const name = filename.replace(/\.[^/.]+$/, '');
  return `${folder}/${prefix}-${name}-${timestamp}`;
}

PayloadDocument

Simplified Payload document type for use with thumbnails and transformations.

export interface PayloadDocument {
  id?: string;
  filename?: string;
  cloudinary?: CloudinaryMetadata;
  sizes?: Record<string, { url: string; width: number; height: number }>;
  [key: string]: any;
}

Properties

string

Payload document ID.

filename

string

Original filename of the uploaded asset.

cloudinary

CloudinaryMetadata

Cloudinary metadata object. See CloudinaryMetadata.

sizes

Record<string, object>

Image size variations (for Payload image resizing).Each size object contains:

url (string): URL to the sized image
width (number): Width in pixels
height (number): Height in pixels

CloudinaryAdapter

Type alias for the Cloudinary storage adapter.

export type CloudinaryAdapter = Adapter;

This is an alias for the Adapter type from @payloadcms/plugin-cloud-storage/types.

CloudinaryStoragePlugin

Type for the main plugin function.

export type CloudinaryStoragePlugin = (
  cloudinaryArgs: CloudinaryStorageOptions,
) => Plugin;

A function that accepts CloudinaryStorageOptions and returns a Payload Plugin.

Advanced Types

GenerateURLParams

Extended parameters for URL generation with Cloudinary-specific options.

export type GenerateURLParams = Parameters<GenerateURL>[0] & {
  version?: string | number;
  pdf_page?: number;
  format?: string;
};

version

string | number

Specific version to retrieve.

pdf_page

number

Page number for PDF thumbnails.

format

string

Target format for conversion (e.g., "jpg", "png", "webp").

CloudinaryURLResponse

Response object from URL generation.

export type CloudinaryURLResponse = {
  url: string;
  public_id: string;
};

url

string

Generated Cloudinary URL.

public_id

string

Public ID of the asset.

Core

Configuration Options

CloudinaryStorageOptions

Properties

CloudinaryConfig

Properties

Example

CloudinaryMetadata

Properties

CloudinaryVersioningOptions

Properties

Example

PublicIDOptions

Properties

PayloadDocument

Properties

CloudinaryAdapter

CloudinaryStoragePlugin

Advanced Types

GenerateURLParams

CloudinaryURLResponse

See Also

Build docs developers (and LLMs) love

Core

Configuration Options

​CloudinaryStorageOptions

​Properties

​CloudinaryConfig

​Properties

​Example

​CloudinaryMetadata

​Properties

​CloudinaryVersioningOptions

​Properties

​Example

​PublicIDOptions

​Properties

​PayloadDocument

​Properties

​CloudinaryAdapter

​CloudinaryStoragePlugin

​Advanced Types

​GenerateURLParams

​CloudinaryURLResponse

​See Also

Build docs developers (and LLMs) love

CloudinaryStorageOptions

Properties

CloudinaryConfig

Properties

Example

CloudinaryMetadata

Properties

CloudinaryVersioningOptions

Properties

Example

PublicIDOptions

Properties

PayloadDocument

Properties

CloudinaryAdapter

CloudinaryStoragePlugin

Advanced Types

GenerateURLParams

CloudinaryURLResponse

See Also