PayloadCMS Storage Adapter for Cloudflare

A storage adapter for PayloadCMS that enables storing media files on Cloudflare Images and Cloudflare Stream.

Installation

npm install payloadcms-storage-cloudflare
# or
yarn add payloadcms-storage-cloudflare
# or
pnpm add payloadcms-storage-cloudflare

Requirements

• PayloadCMS v3.0.0 or higher
• Cloudflare account with Images and/or Stream enabled
• Cloudflare API token with appropriate permissions

Usage

Add the plugin to your Payload config:

import { buildConfig } from 'payload/config';
import { cloudflareStorage } from 'payloadcms-storage-cloudflare';

export default buildConfig({
  // ... other config
  plugins: [
    cloudflareStorage({
      collections: {
        media: true, // Enable for the Media collection
      },
      config: {
        accountId: env.CLOUDFLARE_ACCOUNT_ID, // Found in the sidebar of your Cloudflare Stream/Image dashboard
        apiToken: env.CLOUDFLARE_API_TOKEN, // Found under your Cloudflare account API tokens
        customerSubdomain: env.CLOUDFLARE_CUSTOMER_SUBDOMAIN, // Found in the sidebar of your Cloudflare Stream dashboard
        imageDeliveryUrl: env.CLOUDFLARE_IMAGE_DELIVERY_URL, // Found in the sidebar of your Cloudflare Image dashboard
      },
    }),
  ],
});

Client Uploads

This adapter supports client-side uploads, which allow files to be uploaded directly from the browser to Cloudflare, bypassing your server entirely. This is especially useful for large video files or when deploying to environments with upload size limitations (like Vercel).

To enable client uploads:

import { buildConfig } from 'payload/config';
import { cloudflareStorage } from 'payloadcms-storage-cloudflare';

export default buildConfig({
  // ... other config
  plugins: [
    cloudflareStorage({
      collections: {
        media: true, // Enable for the Media collection
      },
      config: {
        accountId: env.CLOUDFLARE_ACCOUNT_ID,
        apiToken: env.CLOUDFLARE_API_TOKEN,
        customerSubdomain: env.CLOUDFLARE_CUSTOMER_SUBDOMAIN,
        imageDeliveryUrl: env.CLOUDFLARE_IMAGE_DELIVERY_URL,
      },
      // Enable client uploads with default settings
      clientUploads: true,
      
      // Or use custom access control
      // clientUploads: {
      //   access: ({ req, collectionSlug }) => {
      //     // Custom access control logic
      //     return !!req.user;
      //   }
      // }
    }),
  ],
});

How Client Uploads Work

1. When a user uploads a file in the admin UI, the file is intercepted by the client handler
2. The client requests secure upload URLs from your server (which validates the request)
3. The file is uploaded directly from the browser to Cloudflare
4. Only metadata about the file is sent to your server for storage in the database
5. Your server never handles the actual file data

This approach improves upload performance and works around server upload size limitations.

Configuration Options

Plugin Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | collections | Record<string, boolean \| object> | Yes | Collections to enable the adapter for | | enabled | boolean | No | Whether the plugin is enabled (default: true) | | config | object | Yes | Cloudflare configuration | | clientUploads | boolean \| object | No | Enable client-side uploads (default: false) |

Cloudflare Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | accountId | string | Yes | Your Cloudflare account ID | | apiToken | string | Yes | Your Cloudflare API token | | customerSubdomain | string | No* | Your Cloudflare Stream subdomain | | accountHash | string | No* | Your Cloudflare Images account hash |

* Either customerSubdomain or accountHash is required depending on your use case.

Features

• Upload files to Cloudflare Images and Stream
• Automatic detection of file types (images vs videos)
• Client-side uploads for improved performance
• Supports large file uploads using TUS protocol
• Proper URL generation for different media types
• Handles file deletion

License

MIT