Payload CMS Cloudinary Plugin

https://github.com/syedmuzamilm/payload-cloudinary
Admin
A powerful plugin for Payload CMS that integrates Cloudinary as a storage adapter for media files,...
Tokens:8,505
Snippets:34
Trust Score:7.5
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Development Server Start Command

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

This command initiates the development server for the project using 'bun'. It's a straightforward way to run the application locally during development. No specific inputs or outputs are defined beyond the server starting.

```bash
bun run src/index.ts

```

--------------------------------

### Install Payload Cloudinary Plugin

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Instructions for installing the payload-cloudinary package using various package managers like npm, yarn, pnpm, and bun.

```bash
npm install payload-cloudinary
# or
yarn add payload-cloudinary
# or
pnpm add payload-cloudinary
# or
bun add payload-cloudinary
```

--------------------------------

### Export Media Usage Examples (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Exports the functions for interacting with media assets from the module. This includes functions for getting media by ID, searching media, retrieving version history, and uploading new media. This facilitates the use of these utilities in other parts of the application.

```typescript
// Export usage examples
export { getMediaById, searchMedia, getMediaVersionHistory, uploadMedia };
```

--------------------------------

### Basic Payload CMS Cloudinary Configuration

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Example of how to integrate the Cloudinary storage adapter into your Payload CMS configuration file. This requires Cloudinary credentials and specifies which collections to enable the adapter for.

```typescript
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, // Enable for media collection
        // Add more collections as needed
      },
      folder: 'your-folder-name', // Optional, defaults to 'payload-media'
    })
  ]
});
```

--------------------------------

### Payload CMS Media Collection with Uploads

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Example of defining a 'media' collection in Payload CMS, enabling uploads, and ensuring its slug matches the one configured in the Payload Cloudinary plugin for proper integration.

```typescript
// In your collection definition
export const Media: CollectionConfig = {
  slug: 'media', // This MUST match the slug in your plugin config
  access: {
    read: () => true,
  },
  fields: [
    // Your fields
  ],
  upload: true,
};

// In your payload.config.ts
export default buildConfig({
  // ...
  collections: [Media, Users, etc],
  plugins: [
    cloudinaryStorage({
      collections: {
        'media': true, // Matches the slug in your Media collection
      },
      customFields: [
        // Your custom fields here
      ]
    })
  ]
});
```

--------------------------------

### Generate Custom Media Collection with Cloudinary

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

This example demonstrates using `generateMediaCollection` to create a custom media collection with advanced Cloudinary integration. It allows for a custom public ID generation function, specific versioning settings, and additional custom fields like 'photographer'. It also includes Payload CMS collection configurations for access control and hooks.

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

const MediaWithCloudinary = generateMediaCollection(
  {
    config: {
      cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
      api_key: process.env.CLOUDINARY_API_KEY,
      api_secret: process.env.CLOUDINARY_API_SECRET
    },
    folder: 'custom-media-folder',
    publicID: {
      enabled: true,
      generatePublicID: (filename, prefix, folder) => {
        const sanitizedName = filename
          .toLowerCase()
          .replace(/\.[^/.]+$/, "")
          .replace(/[^a-z0-9]/g, '-')
          .replace(/-+/g, '-')
          .replace(/^-|-$/g, '');
        const timestamp = Date.now();
        return `${folder}/${sanitizedName}_${timestamp}`;
      }
    },
    versioning: {
      enabled: true,
      storeHistory: true,
      autoInvalidate: false
    },
    customFields: [
      {
        name: 'photographer',
        type: 'text',
        label: 'Photographer Name'
      }
    ]
  },
  {
    slug: 'media',
    admin: {
      group: 'Content',
      description: 'Images, videos, and documents stored in Cloudinary',
      useAsTitle: 'filename'
    },
    access: {
      read: () => true,
      create: ({ req: { user } }) => !!user,
      update: ({ req: { user } }) => !!user,
      delete: ({ req: { user } }) => !!user
    },
    hooks: {
      beforeChange: [
        async ({ data, req }) => {
          if (data.alt === '') {
            data.alt = data.filename || 'Untitled';
          }
          return data;
        }
      ]
    }
  }
);

export default buildConfig({
  collections: [MediaWithCloudinary, Users],
  plugins: []
});
```

--------------------------------

### Get Media Version History (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Retrieves the version history for a specific media file from Payload CMS. It returns the current media details and an array of past versions, including their respective URLs and creation timestamps. This is valuable for auditing and reverting media changes.

```typescript
import payload from 'payload';

// Get version history for a media file
const getMediaVersionHistory = async (mediaId: string) => {
  const media = await payload.findByID({
    collection: 'media',
    id: mediaId
  });

  if (!media.versions || media.versions.length === 0) {
    return { current: media.cloudinary, history: [] };
  }

  return {
    current: {
      version: media.cloudinary.version,
      versionId: media.cloudinary.version_id,
      url: media.cloudinary.secure_url,
      createdAt: media.cloudinary.created_at
    },
    history: media.versions.map(v => ({
      version: v.version,
      versionId: v.version_id,
      url: v.secure_url,
      createdAt: v.created_at
    }))
  };
};
```

--------------------------------

### Generate Custom Media Collection with Cloudinary Storage

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Demonstrates how to create a custom media collection using the `generateMediaCollection` utility provided by the payload-cloudinary plugin. This allows for fine-grained control over Cloudinary configuration, folder structure, and collection-specific settings within Payload CMS.

```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
  ],
})
```

--------------------------------

### Configure Cloudinary Storage Plugin for Payload CMS

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

This snippet shows how to initialize the `cloudinaryStorage` plugin within a Payload CMS configuration. It sets up Cloudinary credentials, specifies which collections to apply the storage to, configures folder structures, enables features like PDF thumbnails and versioning, and defines custom fields for media. It uses environment variables for sensitive credentials.

```typescript
import { buildConfig } from 'payload/config';
import { cloudinaryStorage } from 'payload-cloudinary';

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  collections: [Users, Media],
  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,
        'user-avatars': {
          disablePayloadAccessControl: true
        }
      },
      folder: 'my-app/uploads',
      disableLocalStorage: true,
      enabled: true,
      supportDynamicFolderMode: true,
      enablePDFThumbnails: true,
      publicID: {
        enabled: true,
        useFilename: true,
        uniqueFilename: true
      },
      versioning: {
        enabled: true,
        autoInvalidate: true,
        storeHistory: true
      },
      customFields: [
        {
          name: 'alt',
          type: 'text',
          label: 'Alt Text',
          admin: {
            description: 'Alternative text for accessibility'
          }
        },
        {
          name: 'caption',
          type: 'textarea',
          label: 'Caption'
        }
      ]
    })
  ]
});
```

--------------------------------

### Debug Media Collection Fields in Payload CMS

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Provides a TypeScript code snippet for debugging custom fields in the Payload CMS admin UI. The `onInit` hook is used to log the fields of the 'media' collection, helping to identify potential conflicts or misconfigurations.

```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)
    );
  }
});
```

--------------------------------

### React Cloudinary Media Component for Images, Videos, and PDFs

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

This React component handles rendering various Cloudinary asset types including images, videos, and PDFs. For images, it implements responsive loading using srcset. For videos, it provides a player with poster images. For PDFs, it generates thumbnail previews and links to the full document, including page-specific thumbnails for multi-page PDFs. It relies on `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME` environment variable.

```jsx
import React from 'react';

const CloudinaryMedia = ({ media, transformations = '' }) => {
  if (!media?.cloudinary) {
    return <div>No media available</div>;
  }

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

  // Handle PDF files with thumbnail generation
  if (format === 'pdf') {
    const page = selected_page || 1;
    const thumbnailUrl = `https://res.cloudinary.com/${cloudName}/image/upload/pg_${page},w_400,h_500,c_fill,q_auto,f_jpg/${public_id}.pdf`;
    const fullPdfUrl = `https://res.cloudinary.com/${cloudName}/raw/upload/${public_id}.pdf`;

    return (
      <div className="pdf-viewer">
        <a href={fullPdfUrl} target="_blank" rel="noopener noreferrer">
          <img
            src={thumbnailUrl}
            alt={media.alt || media.filename}
            className="pdf-thumbnail"
          />
        </a>
        {pages > 1 && (
          <div className="pdf-info">
            <p>{pages} pages</p>
            <div className="page-grid">
              {Array.from({ length: Math.min(pages, 10) }).map((_, i) => (
                <img
                  key={i}
                  src={`https://res.cloudinary.com/${cloudName}/image/upload/pg_${i + 1},w_80,h_100,c_fill,q_auto,f_jpg/${public_id}.pdf`}
                  alt={`Page ${i + 1}`}
                />
              ))}
            </div>
          </div>
        )}
      </div>
    );
  }

  // Handle video files
  if (resource_type === 'video') {
    return (
      <video
        controls
        width="100%"
        poster={`https://res.cloudinary.com/${cloudName}/video/upload/so_0,w_1200,q_auto,f_jpg/${public_id}.jpg`}
      >
        <source
          src={`https://res.cloudinary.com/${cloudName}/video/upload/q_auto,f_auto/${public_id}.${format}`}
          type={`video/${format}`}
        />
      </video>
    );
  }

  // Handle images with responsive srcset
  return (
    <picture>
      <source
        media="(max-width: 640px)"
        srcSet={`https://res.cloudinary.com/${cloudName}/image/upload/w_640,c_limit,q_auto,f_auto,${transformations}/${public_id}.${format}`}
      />
      <source
        media="(max-width: 1024px)"
        srcSet={`https://res.cloudinary.com/${cloudName}/image/upload/w_1024,c_limit,q_auto,f_auto,${transformations}/${public_id}.${format}`}
      />
      <source
        media="(max-width: 1920px)"
        srcSet={`https://res.cloudinary.com/${cloudName}/image/upload/w_1920,c_limit,q_auto,f_auto,${transformations}/${public_id}.${format}`}
      />
      <img
        src={`https://res.cloudinary.com/${cloudName}/image/upload/w_1920,c_limit,q_auto,f_auto,${transformations}/${public_id}.${format}`}
        alt={media.alt || media.filename}
        loading="lazy"
      />
    </picture>
  );
};

// Usage example
const MediaGallery = ({ items }) => {
  return (
    <div className="gallery">
      {items.map(item => (
        <CloudinaryMedia
          key={item.id}
          media={item}
          transformations="e_sharpen:100,e_improve"
        />
      ))}
    </div>
  );
};

export default CloudinaryMedia;

```

--------------------------------

### Handle Cloudinary File Uploads

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Handles file uploads to Cloudinary, supporting custom public IDs, versioning, and automatic resource type detection (image, video, raw). It configures Cloudinary with credentials and specific upload options based on the provided configuration.

```typescript
import { v2 as cloudinary } from 'cloudinary';
import { getHandleUpload } from './handleUpload';

cloudinary.config({
  cloud_name: 'demo-cloud',
  api_key: 'your-api-key',
  api_secret: 'your-api-secret'
});

const uploadHandler = getHandleUpload({
  cloudinary,
  collection: mediaCollection,
  folder: 'uploads',
  prefix: 'user-123',
  versioning: {
    enabled: true,
    autoInvalidate: true,
    storeHistory: true
  },
  publicID: {
    enabled: true,
    useFilename: true,
    uniqueFilename: true
  }
});

// Example upload with PDF file
const result = await uploadHandler({
  data: {
    prefix: 'documents',
    filename: 'report.pdf',
    mimeType: 'application/pdf'
  },
  file: {
    buffer: pdfBuffer,
    filename: 'report.pdf',
    mimetype: 'application/pdf'
  }
});

// Result structure
console.log(result.cloudinary);
```

--------------------------------

### Payload Cloudinary Versioning Support Configuration

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Enables and configures versioning features for media files stored in Cloudinary. Options include automatic invalidation of old versions in the CDN and storing version history within the Payload CMS database.

```typescript
cloudinaryStorage({
  // ... other options
  versioning: {
    enabled: true, // Enable versioning support
    autoInvalidate: true, // Automatically invalidate old versions in CDN
    storeHistory: true, // Store version history in PayloadCMS database
  },
})
```

--------------------------------

### Serve Cloudinary Files with Payload Static Handler (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Implements an HTTP handler to serve Cloudinary-hosted files through Payload CMS. It supports ETag-based caching and generates thumbnails for PDFs. This handler can be integrated with frameworks like Express.

```typescript
import { getHandler } from './staticHandler';
import { v2 as cloudinary } from 'cloudinary';

cloudinary.config({
  cloud_name: 'demo-cloud',
  api_key: 'your-api-key',
  api_secret: 'your-api-secret'
});

const staticHandler = getHandler({
  cloudinary,
  collection: mediaCollection,
  folder: 'uploads'
});

// Example Express route
app.get('/api/media/:filename', async (req, res) => {
  const response = await staticHandler(req, {
    params: { filename: req.params.filename }
  });

  if (response.status === 200) {
    const blob = await response.blob();
    res.set('Content-Type', response.headers.get('Content-Type'));
    res.set('ETag', response.headers.get('ETag'));
    res.send(Buffer.from(await blob.arrayBuffer()));
  } else if (response.status === 304) {
    res.status(304).send();
  } else {
    res.status(response.status).send(response.statusText);
  }
});

// Request with PDF thumbnail: GET /api/media/document.pdf?thumbnail=true
// Returns: JPEG thumbnail of first page of the PDF
```

--------------------------------

### Payload Cloudinary Custom Fields Configuration

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Demonstrates how to define custom fields for your media collection when using the Payload Cloudinary plugin. These fields can include text inputs, arrays, and more, enhancing media metadata management.

```typescript
cloudinaryStorage({
  // ... other options
  customFields: [
    {
      name: 'alt',
      type: 'text',
      label: 'Alt Text',
      admin: {
        description: 'Alternative text for accessibility',
      },
    },
    {
      name: 'caption',
      type: 'text',
      label: 'Caption',
    },
    {
      name: 'tags',
      type: 'array',
      label: 'Tags',
      fields: [
        {
          name: 'tag',
          type: 'text',
          required: true,
        },
      ],
    },
    // Add any other fields you need
  ],
})
```

--------------------------------

### Generate Cloudinary URLs

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Generates URLs for accessing media files stored in Cloudinary. It supports versioning, automatic format and quality optimization, and special handling for PDF thumbnails by specifying the page number and desired format.

```typescript
import { getGenerateURL } from './generateURL';

const generateURL = getGenerateURL({
  config: {
    cloud_name: 'demo-cloud',
    api_key: 'your-api-key',
    api_secret: 'your-api-secret'
  },
  folder: 'uploads',
  versioning: {
    enabled: true
  }
});

// Generate URL for a regular image
const imageUrl = generateURL({
  filename: 'photo.jpg',
  prefix: 'gallery'
});
// Returns: 'https://res.cloudinary.com/demo-cloud/image/upload/f_auto,q_auto/uploads/gallery/photo.jpg'

// Generate URL with specific version
const versionedUrl = generateURL({
  filename: 'photo.jpg',
  prefix: 'gallery',
  version: '1673456789'
});
// Returns: 'https://res.cloudinary.com/demo-cloud/image/upload/v1673456789/f_auto,q_auto/uploads/gallery/photo.jpg'

// Generate thumbnail URL for PDF
const pdfThumbnail = generateURL({
  filename: 'document.pdf',
  prefix: 'docs',
  format: 'jpg',
  pdf_page: 3
});
// Returns: 'https://res.cloudinary.com/demo-cloud/image/upload/pg_3,f_jpg,q_auto/uploads/docs/document.pdf'

// Generate video URL
const videoUrl = generateURL({
  filename: 'video.mp4',
  prefix: 'videos'
});
// Returns: 'https://res.cloudinary.com/demo-cloud/video/upload/f_auto,q_auto/uploads/videos/video.mp4'
```

--------------------------------

### Access Version History in PayloadCMS - TypeScript

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Shows how to access and iterate through the version history of a media document stored via the Payload Cloudinary plugin using TypeScript. Includes accessing current version details.

```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}`);

```

--------------------------------

### Media Collection Structure with Cloudinary Metadata - TypeScript

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Defines the TypeScript structure for media documents when using the Payload Cloudinary plugin. Includes standard PayloadCMS fields, Cloudinary metadata, optional version history, and PDF-specific fields.

```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
}

```

--------------------------------

### Search Media with Filtering and Sorting (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Searches for media documents in Payload CMS based on a query string that can match filenames, alt text, or captions. It returns a limited list of media objects, each including its ID, filename, Cloudinary URL, public ID, and a thumbnail URL. This is useful for implementing media search functionalities.

```typescript
import payload from 'payload';

// Query media with filtering and sorting
const searchMedia = async (query: string, limit: number = 20) => {
  const results = await payload.find({
    collection: 'media',
    where: {
      or: [
        { filename: { contains: query } },
        { alt: { contains: query } },
        { caption: { contains: query } }
      ]
    },
    limit,
    sort: '-createdAt'
  });

  return results.docs.map(doc => ({
    id: doc.id,
    filename: doc.filename,
    url: doc.cloudinary.secure_url,
    publicId: doc.cloudinary.public_id,
    thumbnailUrl: doc.cloudinary.format === 'pdf'
      ? doc.cloudinary.thumbnail_url
      : doc.cloudinary.secure_url
  }));
};
```

--------------------------------

### Display PDF Viewer in Frontend Component - JSX

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

A React component for displaying PDF files uploaded via the Payload Cloudinary plugin. It handles PDF page display, thumbnail generation, and navigation. Relies on Cloudinary's URL format for image and PDF rendering. Assumes `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME` environment variable is set.

```jsx
const PDFViewer = ({ media }) => {
  if (!media?.cloudinary || media.cloudinary.format !== 'pdf') {
    return null;
  }

  const { public_id, pages, selected_page } = media.cloudinary;
  const cloudName = process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME;
  const page = selected_page || 1;

  return (
    <div className="pdf-viewer">
      <h2>{media.filename}</h2>

      {/* Display the selected page as a thumbnail */}
      <a href={`https://res.cloudinary.com/${cloudName}/image/upload/${public_id}.pdf`} target="_blank">
        <img
          src={`https://res.cloudinary.com/${cloudName}/image/upload/pg_${page},w_300,h_400,c_fill,q_auto,f_jpg/${public_id}.pdf`}
          alt={`PDF Page ${page}`}
        />
      </a>

      {/* Page navigation if there are multiple pages */}
      {pages > 1 && (
        <div className="pdf-pages">
          <p>Page {page} of {pages}</p>

          {/* Thumbnail grid of all pages */}
          <div className="page-thumbnails">
            {Array.from({ length: pages }).map((_, i) => (
              <img
                key={i}
                src={`https://res.cloudinary.com/${cloudName}/image/upload/pg_${i + 1},w_100,h_130,c_fill,q_auto,f_jpg/${public_id}.pdf`}
                alt={`Page ${i + 1}`}
                className={i + 1 === page ? 'active' : ''}
              />
            ))}
          </div>
        </div>
      )}
    </div>
  );
};

```

--------------------------------

### React Component for Cloudinary Image Display

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

A React component that renders an image from Cloudinary using its public ID. It supports responsive image loading by specifying different image widths based on media query breakpoints. It depends on a Cloudinary public ID and format being available in the `media.cloudinary` object and the `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME` environment variable.

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

```

--------------------------------

### Upload Media Programmatically (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Uploads a new media file to Payload CMS programmatically. It accepts the file buffer, filename, and optional metadata (like alt text and caption). The function returns details of the uploaded media, including its ID, filename, and Cloudinary information. This is essential for backend media uploads.

```typescript
import payload from 'payload';

// Upload new media programmatically
const uploadMedia = async (fileBuffer: Buffer, filename: string, metadata: any = {}) => {
  const result = await payload.create({
    collection: 'media',
    data: {
      alt: metadata.alt || filename,
      caption: metadata.caption || ''
    },
    file: {
      data: fileBuffer,
      name: filename,
      mimetype: metadata.mimetype || 'application/octet-stream'
    }
  });

  return {
    id: result.id,
    filename: result.filename,
    cloudinary: result.cloudinary
  };
};
```

--------------------------------

### Payload Cloudinary Public ID Customization

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Configuration options for customizing how public IDs are generated in Cloudinary. This includes options to enable custom generation, use filenames, ensure uniqueness, and provide a custom generator function for flexible naming conventions.

```typescript
cloudinaryStorage({
  // ... other options
  publicID: {
    enabled: true, // Enable custom public ID generation
    useFilename: true, // Use the original filename in the public ID
    uniqueFilename: true, // Add a unique identifier to prevent collisions
    // Optional custom generator function
    generatePublicID: (filename, prefix, folder) => {
      // Create a sanitized slug from the filename
      const sanitizedName = filename
        .toLowerCase()
        .replace(/\.[^/.]+$/, '')
        .replace(/[^a-z0-9]/g, '-')
        .replace(/-+/g, '-')
        .replace(/^-|-$/g, '');

      // Add timestamp for uniqueness
      const timestamp = new Date().toISOString().replace(/[^0-9]/g, '').slice(0, 14);
      const prefixPath = prefix ? `${prefix}/` : '';

      return `${folder}/${prefixPath}${sanitizedName}_${timestamp}`;
    },
  },
})
```

--------------------------------

### Fetch Media by ID with Cloudinary Metadata (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Fetches a single media document by its ID from Payload CMS and returns a structured object containing essential Cloudinary metadata and custom fields like alt text and caption. This function is useful for retrieving detailed information about a specific media asset.

```typescript
import payload from 'payload';

// Fetch a single media document with full Cloudinary metadata
const getMediaById = async (mediaId: string) => {
  const media = await payload.findByID({
    collection: 'media',
    id: mediaId
  });

  return {
    id: media.id,
    filename: media.filename,
    url: media.cloudinary.secure_url,
    publicId: media.cloudinary.public_id,
    format: media.cloudinary.format,
    size: media.cloudinary.bytes,
    dimensions: {
      width: media.cloudinary.width,
      height: media.cloudinary.height
    },
    version: media.cloudinary.version,
    versionId: media.cloudinary.version_id,
    uploadedAt: media.cloudinary.created_at,
    customFields: {
      alt: media.alt,
      caption: media.caption
    }
  };
};
```

--------------------------------

### Generate Custom Public IDs for Cloudinary Media (TypeScript)

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Provides a function to generate custom public IDs for Cloudinary uploads, enabling structured organization. This function creates hierarchical paths including dates, optional prefixes, and handles file naming for raw files.

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

const customPublicIDGenerator = (filename: string, prefix?: string, folder?: string): string => {
  // Extract filename without extension
  const nameWithoutExt = filename.replace(/\.[^/.]+$/, '');

  // Create URL-safe slug
  const slug = nameWithoutExt
    .toLowerCase()
    .normalize('NFD')
    .replace(/[\u0300-\u036f]/g, '') // Remove diacritics
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-+|-+$/g, '');

  // Add date-based organization
  const now = new Date();
  const year = now.getFullYear();
  const month = String(now.getMonth() + 1).padStart(2, '0');
  const day = String(now.getDate()).padStart(2, '0');
  const timestamp = now.getTime();

  // Build hierarchical path
  const datePath = `${year}/${month}/${day}`;
  const prefixPath = prefix ? `${prefix}/` : '';
  const folderPath = folder || 'media';

  // Final public ID with extension for raw files
  const ext = filename.match(/\.[^/.]+$/)?.[0] || '';
  const isRawFile = !['.jpg', '.jpeg', '.png', '.gif', '.webp', '.mp4', '.mov'].includes(ext.toLowerCase());
  const finalName = isRawFile ? `${slug}_${timestamp}${ext}` : `${slug}_${timestamp}`;

  return `${folderPath}/${datePath}/${prefixPath}${finalName}`;
};

export default buildConfig({
  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 },
      folder: 'organized-media',
      publicID: {
        enabled: true,
        generatePublicID: customPublicIDGenerator
      }
    })
  ]
});

// Example output: 'organized-media/2023/01/15/my-awesome-photo_1673798400000'
```

--------------------------------

### Disable Dynamic Folder Mode Support in Cloudinary Plugin

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Shows how to explicitly disable the dynamic folder mode support within the `cloudinaryStorage` plugin configuration. This is useful if you are using a Fixed Folder Mode account or have specific requirements that conflict with dynamic folder handling.

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

--------------------------------

### Handle Cloudinary File Deletion

Source: https://context7.com/syedmuzamilm/payload-cloudinary/llms.txt

Handles the deletion of files from Cloudinary when corresponding media documents are removed from Payload CMS. It retrieves Cloudinary metadata (public_id, resource_type) from the document and invalidates the CDN cache for the deleted file.

```typescript
import { v2 as cloudinary } from 'cloudinary';
import { getHandleDelete } from './handleDelete';

cloudinary.config({
  cloud_name: 'demo-cloud',
  api_key: 'your-api-key',
  api_secret: 'your-api-secret'
});

const deleteHandler = getHandleDelete({
  cloudinary,
  folder: 'uploads'
});

// Example deletion
await deleteHandler({
  filename: 'image-123.jpg',
  doc: {
    id: 'doc-123',
    filename: 'image-123.jpg',
    cloudinary: {
      public_id: 'uploads/user-files/image-123',
      resource_type: 'image',
      type: 'upload',
      format: 'jpg',
      secure_url: 'https://res.cloudinary.com/demo-cloud/image/upload/v123456789/uploads/user-files/image-123.jpg',
      bytes: 102400,
      created_at: '2023-01-11T10:00:00Z'
    }
  }
});

// Console output: "Successfully deleted uploads/user-files/image-123 from Cloudinary"
```

--------------------------------

### Access Cloudinary Public ID in PayloadCMS - TypeScript

Source: https://github.com/syedmuzamilm/payload-cloudinary/blob/main/README.md

Demonstrates how to retrieve the Cloudinary public ID from upload responses and document queries within a PayloadCMS application using TypeScript.

```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;

```
Tokens:
Raw