or

or

Basic Configuration

Here's how to use the plugin in your Payload CMS configuration:

`typescript
{
// Standard PayloadCMS fields
id: string;
filename: string;
mimeType: string;
filesize: number;
width?: number;
height?: number;
createdAt: string;
updatedAt: string;

// Cloudinary metadata
cloudinary: {
public_id: string; // Cloudinary public ID
resource_type: string; // 'image', 'video', or 'raw'
format: string; // File extension
secure_url: string; // Full Cloudinary URL
bytes: number; // File size in bytes
created_at: string; // Cloudinary upload timestamp
version: string; // Current version number
version_id: string; // Current version ID
width?: number; // For images and videos
height?: number; // For images and videos
duration?: number; // For videos only
};

// Version history (if enabled)
versions?: Array<{
version: string; // Version number
version_id: string; // Version ID
created_at: string; // Version creation timestamp
secure_url: string; // URL for this version
}>;

// PDF-specific fields (if applicable)
cloudinary: {
// ... other cloudinary fields
pages?: number; // Number of pages in PDF
selected_page?: number; // Currently selected page for thumbnail
};

// Your custom fields (if configured)
alt?: string;
caption?: string;
tags?: Array<{ tag: string }>;
// ... any other custom fields
}
`

$3

The public_id field is now directly accessible in both upload responses and document queries:

`typescript
// In upload response
const uploadResponse = await payload.create({
collection: 'media',
data: {
filename: 'example.jpg',
mimeType: 'image/jpeg',
},
});
const publicId = uploadResponse.data.cloudinary.public_id;

// In document queries
const doc = await payload.findByID({
collection: 'media',
id: 'your-doc-id',
});
const publicId = doc.cloudinary.public_id;
`

$3

If versioning is enabled, you can access the complete version history:

`typescript
const doc = await payload.findByID({
collection: 'media',
id: 'your-doc-id',
});

// Access all versions
doc.versions?.forEach(version => {
console.log(Version ${version.version} created at ${version.created_at});
console.log(URL: ${version.secure_url});
});

// Access current version
console.log(Current version: ${doc.cloudinary.version});
console.log(Current version ID: ${doc.cloudinary.version_id});
`

Custom Media Collection

If you want more control over your Media collection, you can use the generateMediaCollection utility:

`typescript
import { generateMediaCollection, cloudinaryStorage } from 'payload-cloudinary';

export default buildConfig({
// ... your other config
plugins: [
// Register the plugin without a media collection
cloudinaryStorage({
// ... your plugin options
collections: {}, // No collections here
}),
],
collections: [
// Create a custom media collection
generateMediaCollection(
{
config: {
cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
api_key: process.env.CLOUDINARY_API_KEY,
api_secret: process.env.CLOUDINARY_API_SECRET,
},
folder: 'my-payload-cms',
publicID: {
// Public ID options...
},
versioning: {
// Versioning options...
},
},
// Additional collection configuration
{
admin: {
description: 'Media files stored in Cloudinary',
group: 'Content',
},
hooks: {
// Add your own hooks here
},
}
),
// Your other collections
],
})
`

Dynamic Folder Mode Support

Cloudinary has two folder modes: Fixed Folder Mode (older accounts) and Dynamic Folder Mode (newer accounts). This plugin now supports both modes by default.

$3

Dynamic Folder Mode separates the folder structure seen in the Cloudinary Media Library UI (asset_folder) from the public ID path. This means:

1. Assets can be organized in the Media Library UI independently of their public IDs
2. Moving assets between folders in the UI doesn't break existing URLs
3. API responses include asset_folder and display_name instead of just folder

$3

By default, this plugin now adds the asset_folder parameter to all uploads, setting it to match the folder path. This ensures that:

1. Assets appear in the expected folders in Cloudinary's Media Library UI
2. The folder structure is preserved regardless of your account's folder mode
3. Public IDs are still generated according to your configuration

You can disable this feature if needed:

`typescript
cloudinaryStorage({
// ... other options
supportDynamicFolderMode: false
})
`

$3

If you need to test your application with different folder modes:

1. For Fixed Folder Mode (older accounts):
- Assets appear in folders matching their public ID path
- API responses include the folder field

2. For Dynamic Folder Mode (newer accounts):
- Assets appear in folders according to the asset_folder parameter
- API responses include asset_folder and display_name fields
- Moving assets in the Media Library doesn't change their public IDs

Troubleshooting

$3

If your custom fields aren't showing up in the Payload CMS admin panel:

1. Check Collection Slug: Ensure the collection slug in your plugin configuration matches exactly with your Media collection slug.

2. Plugin Order: Make sure the cloudinaryStorage plugin is registered before your collections are processed. In some cases, it might help to move the plugin earlier in your plugins array.

3. Check for Field Conflicts: If you already have fields with the same names in your collection, there might be conflicts. Try using different field names or debug by checking the complete list of fields after plugin initialization.

4. Restart Your Dev Server: Sometimes a full restart of your development server is needed after making plugin configuration changes.

5. Debug Plugin Configuration: You can add a temporary debug log to see what's happening:

`typescript
export default buildConfig({
// ... your config
onInit: async (payload) => {
// Log the complete Media collection configuration
console.log('Media collection fields:',
payload.collections['media'].config.fields.map(f => f.name)
);
}
});
`

Using Cloudinary URLs in Frontend Components

Here's an example React component that uses the Cloudinary public ID for transformations:

`jsx
const CloudinaryImage = ({ media }) => {
if (!media?.cloudinary) return null;

const { public_id, format } = media.cloudinary;
const cloudName = process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME;

// You can use Cloudinary transformations in the URL
return (

media="(max-width: 640px)"
srcSet={https://res.cloudinary.com/${cloudName}/image/upload/w_400,c_limit,q_auto,f_auto/${public_id}.${format}}
/>
media="(max-width: 1024px)"
srcSet={https://res.cloudinary.com/${cloudName}/image/upload/w_800,c_limit,q_auto,f_auto/${public_id}.${format}}
/>
src={https://res.cloudinary.com/${cloudName}/image/upload/q_auto,f_auto/${public_id}.${format}}
alt={media.alt || media.filename}
loading="lazy"
/>

);
};
`

Complete Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| config | Object | (required) | Cloudinary API credentials |
| config.cloud_name | string | (required) | Your Cloudinary cloud name |
| config.api_key | string | (required) | Your Cloudinary API key |
| config.api_secret | string | (required) | Your Cloudinary API secret |
| collections | Object | (required) | Collections that should use Cloudinary storage |
| folder | string | 'payload-media' | Base folder path in Cloudinary |
| disableLocalStorage | boolean | true | Whether to disable local storage |
| enabled | boolean | true | Whether to enable the plugin |
| customFields | Field[] | [] | Custom fields to add to the media collection |
| supportDynamicFolderMode | boolean | true | Whether to support Dynamic Folder Mode for newer Cloudinary accounts |
| publicID | Object | (see below) | Public ID configuration options |
| publicID.enabled | boolean | true | Whether to enable custom public ID generation |
| publicID.useFilename | boolean | true | Whether to use filename in public ID |
| publicID.uniqueFilename | boolean | true | Whether to ensure unique filenames |
| publicID.generatePublicID | Function | (built-in) | Custom function to generate public ID |
| versioning | Object | (see below) | Versioning configuration options |
| versioning.enabled | boolean | false | Whether to enable versioning support |
| versioning.autoInvalidate | boolean | false | Whether to invalidate old versions in CDN |
| versioning.storeHistory | boolean | false | Whether to store version history in database |

Development

To run the project in development mode:

`bash
bun run src/index.ts
`

Contributing

Contributions to improve the plugin are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

License

This project is open-source. See the LICENSE file for more details.

Contact

For any questions or support, please contact Syed Muzamil.