Skip to main content
The Payload Cloudinary plugin requires a few essential configuration options to connect to your Cloudinary account and specify which collections should use Cloudinary storage.

​
Required Configuration

​
Cloudinary Credentials

The config object contains your Cloudinary API credentials. These are required for the plugin to authenticate with Cloudinary.
​
config
CloudinaryConfig
required
Cloudinary API credentials object
​
config.cloud_name
string
required
Your Cloudinary cloud name. Find this in your Cloudinary dashboard.
​
config.api_key
string
required
Your Cloudinary API key. Generate this in your Cloudinary console.
​
config.api_secret
string
required
Your Cloudinary API secret. Keep this secure and never expose it in client-side code.
import { buildConfig } from 'payload/config';
import { cloudinaryStorage } from 'payload-cloudinary';

export default buildConfig({
  // ... your payload config
  plugins: [
    cloudinaryStorage({
      config: {
        cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
        api_key: process.env.CLOUDINARY_API_KEY,
        api_secret: process.env.CLOUDINARY_API_SECRET
      },
      collections: {
        'media': true,
      },
    })
  ]
});
Never hardcode your Cloudinary credentials in your source code. Always use environment variables to keep them secure.

​
Collections

​
collections
Record<string, CollectionOptions | true>
required
Object mapping collection slugs to their Cloudinary configuration. Use true for default settings or provide a CollectionOptions object for advanced configuration.
The collections option specifies which Payload collections should use Cloudinary for file storage. You can:
  • Use true for default behavior
  • Pass a CollectionOptions object for advanced configuration (from @payloadcms/plugin-cloud-storage)
cloudinaryStorage({
  config: { /* ... */ },
  collections: {
    'media': true, // Use defaults
    'documents': {
      // Advanced options from cloud storage plugin
      generateFileURL: (args) => {
        // Custom URL generation logic
        return args.filename;
      },
    },
  },
})

​
Folder Structure

​
folder
string
default:"payload-media"
The base folder path in Cloudinary where uploaded files will be stored.
Organize your media files in Cloudinary by specifying a folder path: 
cloudinaryStorage({
  config: { /* ... */ },
  collections: { 'media': true },
  folder: 'my-app/uploads', // Files will be stored under this folder
})
With a custom folder:
  • Files upload to: my-app/uploads/filename.jpg
  • Public IDs become: my-app/uploads/filename
  • Easy to organize multiple projects in one Cloudinary account

​
Local Storage

​
disableLocalStorage
boolean
default:true
Whether to disable local file storage. When true, files are only stored in Cloudinary.
By default, the plugin disables local storage to save disk space. All files are uploaded directly to Cloudinary. 
cloudinaryStorage({
  config: { /* ... */ },
  collections: { 'media': true },
  disableLocalStorage: true, // Default - files only in Cloudinary
})
When disableLocalStorage is true, the plugin automatically sets upload.disableLocalStorage to true for all configured collections.

​
Plugin Toggle

​
enabled
boolean
default:true
Whether to enable the plugin. Set to false to disable Cloudinary storage without removing the plugin configuration.
Useful for conditional enabling based on environment: 
cloudinaryStorage({
  config: { /* ... */ },
  collections: { 'media': true },
  enabled: process.env.NODE_ENV === 'production', // Only in production
})

​
Complete Basic Example

Here’s a complete example with all basic configuration options: 
import { buildConfig } from 'payload/config';
import { cloudinaryStorage } from 'payload-cloudinary';

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  collections: [
    // Your collections
  ],
  plugins: [
    cloudinaryStorage({
      // Required: Cloudinary credentials
      config: {
        cloud_name: process.env.CLOUDINARY_CLOUD_NAME!,
        api_key: process.env.CLOUDINARY_API_KEY!,
        api_secret: process.env.CLOUDINARY_API_SECRET!,
      },
      
      // Required: Collections to use Cloudinary
      collections: {
        'media': true,
        'documents': true,
      },
      
      // Optional: Custom folder
      folder: 'my-payload-app',
      
      // Optional: Disable local storage (default: true)
      disableLocalStorage: true,
      
      // Optional: Enable/disable plugin (default: true)
      enabled: true,
    })
  ]
});

​
Environment Variables

Create a .env file with your Cloudinary credentials: 
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret
Add .env to your .gitignore to prevent committing credentials to version control.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us