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. 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`	Optional	Rewrite generated public URLs. See URL transforms.
`i18n`	`object`	Optional	Override the TUS toggle button labels per locale.
`enabled`	`boolean`	Optional	Set to `false` to turn the whole plugin off. 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 config on startup and throws a clear error if any of these are missing:

Every collection listed under collections 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.
A per-collection full config must be complete: storage needs apiKey/hostname/zoneName; stream needs apiKey/hostname/libraryId.
purge (globally or on any collection) requires the global accountApiKey.
storage.clientUploads requires Bunny Storage enabled for that collection. A zone with storage.s3 presigns directly; a zone without s3 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.useRedirect: true. See Stream.

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 configurations, see Examples.

Documentation

Configuration

CLI

Guides

Top-level options

Requirements the plugin enforces

Where to go next

​Top-level options

​Requirements the plugin enforces

​Where to go next

Top-level options

Requirements the plugin enforces

Where to go next