Registry / storage / payload-storage-cloudinary

payload-storage-cloudinary

library1.2.1jsnpmunverified

Cloudinary storage adapter for Payload CMS v3. Replaces local file storage with Cloudinary's cloud-based solution, offering automatic image optimization, transformations, and global CDN delivery. Version 1.2.1, actively maintained. Key differentiators: dynamic folder management, transformation presets, upload queue, signed URLs for private files, public previews with watermarks, and smart re-upload prevention.

storage

npm install payload-storage-cloudinary

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PAYLOAD-STORAGE-CL

payload-storage-cloudinary

storagejavascriptv1.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cloudinaryStorage

✓ import { cloudinaryStorage } from 'payload-storage-cloudinary'

✗ import cloudinaryStorage from 'payload-storage-cloudinary'

Named export since v1.0.0. Default import is not available.

PluginConfig

✓ import { cloudinaryStorage, type PluginConfig } from 'payload-storage-cloudinary'

TypeScript users can import the PluginConfig type for type safety.

CloudinaryStorageConfig

✓ import type { CloudinaryStorageConfig } from 'payload-storage-cloudinary'

✗ import { CloudinaryStorageConfig } from 'payload-storage-cloudinary'

TypeScript type only, not a runtime export. Use type import.

Basic setup of Payload CMS with Cloudinary storage plugin, including environment variables for Cloudinary credentials and disabling local storage.

import { buildConfig } from 'payload' import { cloudinaryStorage } from 'payload-storage-cloudinary' export default buildConfig({ collections: [ { slug: 'media', 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: true, }, }), ], })

Debug

Known issues

breakingThis plugin requires Payload CMS v3. It is not compatible with Payload v2 or earlier.

fix

Ensure your project uses Payload CMS v3.0.0 or later.

affects: >=1.0.0 <2.0.0

breakingThe 'disableLocalStorage' option must be set to true on upload collections when using this plugin.

fix

In your upload collection config, set upload.disableLocalStorage to true.

affects: >=1.0.0

deprecatedThe 'url' field behavior changed in v1.1.0: now always contains the original URL when preserveOriginal is true.

fix

If you relied on the old behavior (url containing transformed URL), use 'transformedUrl' field instead.

affects: >=1.1.0

gotchaCloudinary API credentials must be set in environment variables. Do not hardcode them in the config.

fix

Use process.env variables for cloud_name, api_key, and api_secret.

affects: >=1.0.0

gotchaThe plugin uses Cloudinary's upload API; be aware of Cloudinary's rate limits and pricing for high-volume uploads.

fix

Monitor usage via Cloudinary dashboard, consider queue system for large files.

affects: >=1.0.0

Errors

Common errors & fixes

Error: CloudinaryStorage requires plugin config "collections" to be an object or collection slugs to be defined.

Missing or incorrect 'collections' configuration in plugin options.

fix

Provide a collections object with at least one collection, e.g., cloudinaryStorage({ collections: { media: true } })

PayloadError: Upload collection must have disableLocalStorage set to true when using Cloudinary plugin.

Upload collection configuration does not have disableLocalStorage: true.

fix

Add 'upload: { disableLocalStorage: true }' to your upload collection config.

Error: Cannot find module 'payload-storage-cloudinary'

Package not installed or import path incorrect.

fix

Run 'npm install payload-storage-cloudinary' and ensure import is from the package name.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

@payloadcms/uirequiredRequired by Payload CMS admin panel

payloadrequiredPeer dependency for Payload CMS core

reactrequiredPeer dependency for React rendering

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nlvcodes/payload-storage-cloudinary ↗

packagepayload-storage-cloudinary ↗

homepagehttps://github.com/nlvcodes/payload-storage-cloudinary#readme ↗