Examples

Copy-ready configurations for common setups. Each one is a complete bunnyStorage(...) call — combine pieces as needed for your project. For option-by-option reference, see Configuration.

Starting from scratch? The setup wizard provisions your Bunny resources and prints a ready-to-paste config plus .env lines. Run it first, then use these examples to tune the result.

Basic setup

Storage only

payload.config.ts

import { buildConfig } from 'payload'
import { bunnyStorage } from '@seshuk/payload-storage-bunny'

export default buildConfig({
  plugins: [
    bunnyStorage({
      collections: {
        media: true,
      },
      storage: {
        apiKey: process.env.BUNNY_STORAGE_API_KEY,
        hostname: 'example.b-cdn.net',
        zoneName: 'my-zone',
      },
    }),
  ],
})

With cache purging

bunnyStorage({
  accountApiKey: process.env.BUNNY_ACCOUNT_API_KEY, // required for purge
  collections: {
    media: true,
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
  },
  purge: true,
})

See Cache purging.

Streaming video

Direct CDN vs Payload access control

Two ways to serve Stream videos, depending on whether the collection uses Payload’s access control.

Direct CDN access (fastest)
Payload access control

Files bypass Payload’s access control and stream straight from Bunny.

bunnyStorage({
  accountApiKey: process.env.BUNNY_ACCOUNT_API_KEY,
  collections: {
    media: {
      prefix: 'uploads',
      disablePayloadAccessControl: true,
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    region: 'ny',
    zoneName: 'my-zone',
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    thumbnailTime: 5000,
    tus: true,
  },
  purge: true,
})

Files go through Payload’s own access rules. Stream videos need mp4Fallback or signed URLs with redirect — see Access control and mp4Fallback.

bunnyStorage({
  accountApiKey: process.env.BUNNY_ACCOUNT_API_KEY,
  collections: {
    media: {
      prefix: 'uploads',
      signedUrls: {
        expiresIn: 3600,
        allowedCountries: ['US', 'CA', 'GB'],
        staticHandler: { useRedirect: true },
      },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    region: 'ny',
    zoneName: 'my-zone',
    tokenSecurityKey: process.env.BUNNY_STORAGE_TOKEN_SECURITY_KEY,
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    thumbnailTime: 5000,
    tokenSecurityKey: process.env.BUNNY_STREAM_TOKEN_SECURITY_KEY,
    tus: {
      autoMode: true,
      expiresIn: 3600,
    },
    cleanup: {
      maxAge: 86400,
      schedule: { cron: '0 2 * * *', queue: 'storage-bunny' },
    },
  },
  purge: true,
})

TUS resumable uploads for large videos

bunnyStorage({
  collections: {
    videos: {
      prefix: 'video-content',
      disablePayloadAccessControl: true,
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
    uploadTimeout: 300000,
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    uploadTimeout: 600000,
    tus: {
      autoMode: true,
      expiresIn: 7200, // 2 hours for large files
      checkAccess: (req) => req.user?.role === 'admin' || req.user?.role === 'editor',
    },
    cleanup: true,
  },
})

See Stream: TUS resumable uploads.

Stream only, no storage

bunnyStorage({
  collections: {
    videos: {
      prefix: 'videos',
      disablePayloadAccessControl: true,
    },
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    mp4Fallback: true,
    thumbnailTime: 2000,
    tus: {
      autoMode: true,
      expiresIn: 3600,
    },
    cleanup: {
      maxAge: 86400,
    },
  },
  thumbnail: true,
})

Stream webhook for encoding status

Bunny encodes MP4 renditions asynchronously. Point your Stream library’s webhook at the plugin so that, once encoding finishes, it fills in bunnyData.stream.resolutions. The secret is your library’s Read-Only API key, which Bunny signs each webhook with.

bunnyStorage({
  collections: { media: true },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    mp4Fallback: true, // resolutions are populated once encoding completes
    webhook: {
      secret: process.env.BUNNY_STREAM_READONLY_API_KEY, // library Read-Only API key
    },
  },
})

In your Bunny Stream library settings, set the webhook URL to https://your-site.com/api/storage-bunny/stream/webhook (no query secret). See Webhooks.

Secure access

Signed URLs

bunnyStorage({
  collections: {
    media: {
      signedUrls: {
        expiresIn: 7200,
        allowedCountries: ['US', 'CA', 'GB', 'AU'],
        shouldUseSignedUrl: ({ filename }) => /\.(mp4|webm|mov|avi)$/i.test(filename),
        staticHandler: {
          useRedirect: true,
          redirectStatus: 302,
          expiresIn: 1800,
        },
      },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
    tokenSecurityKey: process.env.BUNNY_STORAGE_TOKEN_SECURITY_KEY,
  },
  signedUrls: {
    expiresIn: 7200,
    blockedCountries: ['CN', 'RU'],
  },
})

See Signed URLs.

IP-locked signed URLs

Bind each signed link to the requesting client’s IPv4 address, so a leaked URL stops working from any other IP. You supply the userIp callback because extracting the real client IP depends on your proxy chain.

bunnyStorage({
  collections: {
    media: {
      signedUrls: {
        expiresIn: 3600,
        staticHandler: { useRedirect: true }, // userIp runs for redirect links
        userIp: ({ req }) => {
          // Pick the header your proxy/CDN sets for the real client IP.
          const forwarded = req.headers.get('x-forwarded-for')
          return forwarded?.split(',')[0]?.trim() || undefined
        },
      },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
    tokenSecurityKey: process.env.BUNNY_STORAGE_TOKEN_SECURITY_KEY,
  },
})

Enforcement requires Token IP Validation enabled on the Bunny zone/library, and only IPv4 is supported. See IP locking.

URLs and thumbnails

Custom URL transforms

bunnyStorage({
  collections: {
    media: {
      urlTransform: {
        appendTimestamp: true,
        queryParams: { version: '2' },
      },
    },
    avatars: {
      urlTransform: {
        transformUrl: ({ baseUrl, filename }) => {
          const size = filename.includes('large') ? '300' : '150'
          return `${baseUrl}?width=${size}&height=${size}&quality=90`
        },
      },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
  },
  thumbnail: {
    appendTimestamp: true,
    queryParams: { width: '200', height: '200', quality: '85' },
  },
})

See URL transforms and Thumbnails.

Named-size thumbnails

payload.config.ts

export default buildConfig({
  collections: [
    {
      slug: 'media',
      upload: {
        imageSizes: [
          { name: 'thumbnail', width: 150, height: 150 },
          { name: 'preview', width: 400, height: 300 },
        ],
      },
      fields: [{ name: 'alt', type: 'text', required: true }],
    },
  ],
  plugins: [
    bunnyStorage({
      collections: {
        media: {
          thumbnail: {
            sizeName: 'thumbnail',
            appendTimestamp: true,
          },
        },
      },
      storage: {
        apiKey: process.env.BUNNY_STORAGE_API_KEY,
        hostname: 'example.b-cdn.net',
        zoneName: 'my-zone',
      },
    }),
  ],
})

Client uploads

Browser-direct client uploads

Send file bytes straight from the browser to Bunny, bypassing the Payload server — useful on serverless hosts with tight body-size limits and for large files. Configure it under storage.clientUploads; the transport is chosen automatically from the zone.

S3 zone
HTTP API zone (edge)

Presigned PUT straight to Bunny’s S3 endpoint. Requires a storage zone created with S3 compatibility — no Edge Script to deploy.

bunnyStorage({
  collections: { media: true },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
    s3: { region: 'de' },
    clientUploads: true, // presigned S3, because storage.s3 is set
  },
})

Proxies the upload through a Bunny Edge Script. Works with any storage zone.

bunnyStorage({
  collections: { media: true },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
    clientUploads: {
      edge: {
        scriptUrl: 'https://my-uploader.b-cdn.net',
        secret: process.env.BUNNY_EDGE_UPLOAD_SECRET,
      },
    },
  },
})

Deploy the Edge Script first with npx payload bunny:deploy-edge-script — it prints the shared edge: { scriptUrl, secret } block to paste here.

See Client uploads.

Multiple zones behind one Edge Script

One deployed Edge Script serves every non-s3 zone. Paste the same edge: { scriptUrl, secret } (printed by npx payload bunny:deploy-edge-script) into each non-s3 zone that enables client uploads; s3 zones presign directly and need no edge config.

bunnyStorage({
  collections: {
    media: true, // uses the global HTTP API zone below
    archive: {
      storage: {
        apiKey: process.env.BUNNY_ARCHIVE_STORAGE_API_KEY,
        hostname: 'archive.b-cdn.net',
        zoneName: 'archive-zone',
        clientUploads: {
          // same script + secret as the global zone
          edge: { scriptUrl: 'https://my-uploader.b-cdn.net', secret: process.env.BUNNY_EDGE_UPLOAD_SECRET },
        },
      },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'main-zone',
    clientUploads: {
      edge: { scriptUrl: 'https://my-uploader.b-cdn.net', secret: process.env.BUNNY_EDGE_UPLOAD_SECRET },
    },
  },
})

Re-run npx payload bunny:deploy-edge-script whenever you add or remove a non-s3 zone, so the script’s zone map stays in sync. To deploy the production script from a dev machine, select the environment explicitly — e.g. npx payload bunny:deploy-edge-script --env-file .env.production. See Deploy the Edge Script.

Multiple collections

Per-collection zones and libraries

Point individual collections at their own Bunny storage zone and stream library. A collection whose storage/stream includes apiKey uses that config as its own zone/library, ignoring the global one. All of apiKey/hostname/zoneName (storage) or apiKey/hostname/libraryId (stream) are then required, and nothing — including tokenSecurityKey, mimeTypes, or tus — is inherited from the global config.

bunnyStorage({
  collections: {
    // Uses the global zone + library
    media: true,
    // Uses its own storage zone and stream library
    tenantA: {
      storage: {
        apiKey: process.env.TENANT_A_STORAGE_API_KEY,
        hostname: 'tenant-a.b-cdn.net',
        zoneName: 'tenant-a-zone',
        tokenSecurityKey: process.env.TENANT_A_STORAGE_TOKEN_KEY,
      },
      stream: {
        apiKey: process.env.TENANT_A_STREAM_API_KEY,
        hostname: 'vz-tenant-a-123.b-cdn.net',
        libraryId: 654321,
        mp4Fallback: true,
        tokenSecurityKey: process.env.TENANT_A_STREAM_TOKEN_KEY, // required: signedUrls on this library
        webhook: { secret: process.env.TENANT_A_WEBHOOK_SECRET },
      },
      signedUrls: { expiresIn: 3600 },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'main-zone',
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    mp4Fallback: true, // media keeps Payload access control, so Stream needs this
    tus: true,
  },
})

See Collection overrides and Multi-tenant.

Disable storage or stream per collection

bunnyStorage({
  collections: {
    // Only Bunny Storage — videos won't be uploaded to Stream
    images: {
      prefix: 'images',
      stream: false,
    },
    // Only Bunny Stream — non-video files are rejected
    videos: {
      prefix: 'videos',
      storage: false,
      disablePayloadAccessControl: true,
    },
    // Both, using global defaults
    media: {
      prefix: 'mixed-content',
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'example.b-cdn.net',
    zoneName: 'my-zone',
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'vz-abc123def-456.b-cdn.net',
    libraryId: 123456,
    mp4Fallback: true, // media keeps Payload access control, so Stream needs this
    tus: true,
  },
})

See Collection overrides.

Different settings per collection

bunnyStorage({
  accountApiKey: process.env.BUNNY_ACCOUNT_API_KEY,
  collections: {
    media: {
      prefix: 'public',
      disablePayloadAccessControl: true,
      thumbnail: {
        appendTimestamp: true,
        queryParams: { width: '200', height: '200' },
      },
    },
    documents: {
      prefix: 'private',
      signedUrls: {
        expiresIn: 1800,
        staticHandler: { useRedirect: false }, // proxy through Payload
      },
      purge: false,
    },
    videos: {
      prefix: 'video-content',
      disablePayloadAccessControl: true,
      stream: {
        thumbnailTime: 3000,
        tus: { expiresIn: 7200 },
      },
    },
    avatars: {
      prefix: 'avatars',
      urlTransform: {
        queryParams: { width: '150', height: '150', quality: '90' },
      },
      purge: { async: true },
    },
  },
  storage: {
    apiKey: process.env.BUNNY_STORAGE_API_KEY,
    hostname: 'cdn.example.com',
    region: 'ny',
    zoneName: 'main-storage',
    tokenSecurityKey: process.env.BUNNY_STORAGE_TOKEN_SECURITY_KEY,
  },
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: 'video.example.com',
    libraryId: 123456,
    mp4Fallback: true,
    tokenSecurityKey: process.env.BUNNY_STREAM_TOKEN_SECURITY_KEY, // documents inherits stream + enables signedUrls
    tus: true,
    cleanup: { maxAge: 172800 },
  },
  purge: true,
  thumbnail: { appendTimestamp: true },
})

Working with stored data

Querying by bunnyData

const results = await payload.find({
  collection: 'media',
  where: {
    'bunnyData.stream.videoId': { equals: 'e7f2c1a0-...' },
  },
})

See Stored data for the full shape and what is stored vs. computed.

Environment variables

.env

# Bunny Storage
BUNNY_STORAGE_API_KEY=your-storage-api-key
BUNNY_STORAGE_TOKEN_SECURITY_KEY=your-storage-token-security-key

# Bunny Stream (optional)
BUNNY_STREAM_API_KEY=your-stream-api-key
BUNNY_STREAM_TOKEN_SECURITY_KEY=your-stream-token-security-key

# Bunny account API key (cache purging + edge-script deploy)
BUNNY_ACCOUNT_API_KEY=your-bunny-account-api-key

# Client uploads (edge mode, optional)
BUNNY_EDGE_UPLOAD_SECRET=your-edge-shared-secret

See Getting your credentials and Cache purging for where each key comes from.

Next steps

Multi-tenant

Per-tenant prefixes, per-tenant zones, and isolation with signed URLs.

Stored data

The bunnyData field shape and querying videos by videoId.

Stream collections

Organize videos into per-tenant Bunny Stream collections.

Media preview

Inline Stream video and audio previews in the admin panel.

Documentation

Configuration

CLI

Guides

Basic setup

Storage only

With cache purging

Streaming video

Direct CDN vs Payload access control

TUS resumable uploads for large videos

Stream only, no storage

Stream webhook for encoding status

Secure access

Signed URLs

IP-locked signed URLs

URLs and thumbnails

Custom URL transforms

Named-size thumbnails

Client uploads

Browser-direct client uploads

Multiple zones behind one Edge Script

Multiple collections

Per-collection zones and libraries

Disable storage or stream per collection

Different settings per collection

Working with stored data

Querying by bunnyData

Environment variables

Next steps

Multi-tenant

Stored data

Stream collections

Media preview

​Basic setup

​Storage only

​With cache purging

​Streaming video

​Direct CDN vs Payload access control

​TUS resumable uploads for large videos

​Stream only, no storage

​Stream webhook for encoding status

​Secure access

​Signed URLs

​IP-locked signed URLs

​URLs and thumbnails

​Custom URL transforms

​Named-size thumbnails

​Client uploads

​Browser-direct client uploads

​Multiple zones behind one Edge Script

​Multiple collections

​Per-collection zones and libraries

​Disable storage or stream per collection

​Different settings per collection

​Working with stored data

​Querying by bunnyData

​Environment variables

​Next steps

Multi-tenant

Stored data

Stream collections

Media preview

Basic setup

Storage only

With cache purging

Streaming video

Direct CDN vs Payload access control

TUS resumable uploads for large videos

Stream only, no storage

Stream webhook for encoding status

Secure access

Signed URLs

IP-locked signed URLs

URLs and thumbnails

Custom URL transforms

Named-size thumbnails

Client uploads

Browser-direct client uploads

Multiple zones behind one Edge Script

Multiple collections

Per-collection zones and libraries

Disable storage or stream per collection

Different settings per collection

Working with stored data

Querying by bunnyData

Environment variables

Next steps