Overview

You configure the plugin with a single bunnyStorage(...) call in your Payload config.

payload.config.ts

bunnyStorage({
  collections: { media: true },
  storage: {/* Bunny Storage credentials */},
  stream: {/* Bunny Stream credentials, optional */},
})

Top-level options

Option	Type	Required	Notes
`collections`	`object`	Required	Which upload collections use Bunny, and their overrides. A value of `false` leaves the collection out. See Collection overrides.
`storage`	`object`	storage or stream	Bunny Storage credentials, including `clientUploads`. See Storage.
`stream`	`object`	storage or stream	Bunny Stream credentials. See Stream.
`accountApiKey`	`string`	Optional	Bunny account API key (AccessKey). Required for cache purging. The same key — passed via the `BUNNY_ACCOUNT_API_KEY` env var or `--api-key` — is what the edge-script deploy CLI needs (it doesn’t read this config field).
`purge`	`boolean \| object`	Optional	Invalidate the CDN on upload and delete. See Cache purging.
`signedUrls`	`boolean \| object`	Optional	Serve time-limited signed URLs. See Signed URLs.
`thumbnail`	`boolean \| object`	Optional	Admin thumbnails for images and Stream videos. See Thumbnails.
`urlTransform`	`boolean \| object \| function`	Optional	Rewrite generated public URLs. See URL transforms.
`enabled`	`boolean`	Optional	Set to `false` to turn the whole plugin off. The hidden storage fields such as `prefix` stay, so the schema matches. Default `true`.

Provide storage, stream, or both at the top level — or omit both and give each collection its own zone or library. The plugin only requires that every collection resolves to at least one active service.

Requirements the plugin enforces

The plugin validates your options on startup and throws a clear error if any of these are missing:

Every collection set to true or an object must end up with at least one active service (storage or stream) after overrides are applied — either from the top-level storage/stream or from a per-collection zone/library.
Per-collection full options must be complete: storage needs apiKey/hostname/zoneName; stream needs apiKey/hostname/libraryId.
purge (globally or on any collection) requires the global accountApiKey.
signedUrls.staticHandler.redirect.status must be 302 or 307.
Removed or renamed v3 options throw an error that names the replacement. See the upgrade guide.
storage.clientUploads requires Bunny Storage enabled for that collection. A zone with storage.s3: true presigns directly; any other zone requires storage.clientUploads.edge.scriptUrl and edge.secret. Non-s3 zones sharing one edge.scriptUrl must use the same edge.secret. See Client uploads.
storage.hostname must be your Pull Zone hostname, not storage.bunnycdn.com.
If signedUrls is enabled and storage is configured, storage.tokenSecurityKey is required.
If signedUrls is enabled and stream is configured, stream.tokenSecurityKey is required.
Any collection using Payload’s access control (the default — disablePayloadAccessControl isn’t true) and Stream needs either mp4Fallback: true or signed URLs with staticHandler.redirect. See Stream.

Translations

The admin UI ships in all 44 languages Payload supports. To change a label, override it in Payload’s own i18n.translations under the @seshuk/payload-storage-bunny key. Your values win over the plugin’s defaults, and keys you leave out keep the default text. The key names are in the English locale file.

export default buildConfig({
  i18n: {
    translations: {
      en: {
        '@seshuk/payload-storage-bunny': {
          tusUploadEnableMode: 'Upload large video',
        },
      },
    },
  },
})

Where to go next

Storage — Bunny Storage credentials and options
Stream — Bunny Stream, TUS uploads, webhooks, cleanup
Client uploads — browser-direct uploads for serverless hosts and large files
Signed URLs — time-limited, geo-restricted access
Thumbnails — admin thumbnails for images and videos
Cache purging — invalidate the CDN on change
URL transforms — rewrite generated URLs
Collection overrides — tune every option per collection

For copy-ready examples, see Examples.

Documentation

Configuration

CLI

Guides

Top-level options

Requirements the plugin enforces

Translations

Where to go next

​Top-level options

​Requirements the plugin enforces

​Translations

​Where to go next

Top-level options

Requirements the plugin enforces

Translations

Where to go next