Quick start

Set up automatically with the wizard, or configure by hand.

Automatic setup

The setup wizard is the fastest path — it provisions the Bunny resources for you and prints a ready-to-paste plugin config plus .env lines, with no manual dashboard steps:

npx @seshuk/payload-storage-bunny init

See Setup wizard for what it asks and everything it creates.

Manual setup

Install

npm install @seshuk/payload-storage-bunny @payloadcms/plugin-cloud-storage

pnpm add @seshuk/payload-storage-bunny @payloadcms/plugin-cloud-storage

yarn add @seshuk/payload-storage-bunny @payloadcms/plugin-cloud-storage

Requires Payload 3.90.2 or later and Node.js 22 or later. @payloadcms/plugin-cloud-storage is a peer dependency. Install the version that matches your Payload version.

On Payload 3.83.0 to 3.90.1, only @seshuk/payload-storage-bunny@3.0.1 works. We do not recommend it, because it lacks the security fixes in v3.1.0. Upgrade Payload instead.

Configure storage

Add the plugin to your Payload config and map an upload collection to Bunny Storage:

payload.config.ts

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

export default buildConfig({
  collections: [
    // your upload collections, e.g. Media
  ],
  plugins: [
    bunnyStorage({
      collections: {
        media: true,
      },
      storage: {
        apiKey: process.env.BUNNY_STORAGE_API_KEY,
        hostname: process.env.BUNNY_STORAGE_HOSTNAME, // e.g. my-zone.b-cdn.net
        zoneName: process.env.BUNNY_STORAGE_ZONE_NAME,
      },
    }),
  ],
})

Files uploaded to the media collection are now stored in Bunny Storage and served from the CDN.

Add video streaming (optional)

To route video uploads to Bunny Stream, add a stream block. Non-video files continue to use Bunny Storage.

payload.config.ts

bunnyStorage({
  collections: { media: true },
  storage: {/* ... */},
  stream: {
    apiKey: process.env.BUNNY_STREAM_API_KEY,
    hostname: process.env.BUNNY_STREAM_HOSTNAME, // e.g. vz-xxxx.b-cdn.net
    libraryId: Number(process.env.BUNNY_STREAM_LIBRARY_ID),
    mp4Fallback: true,
  },
})

With Payload access control on (the default), Stream needs mp4Fallback: true or signed URLs with redirect — otherwise the plugin throws at startup. See Access control and mp4Fallback.Videos now upload to Bunny Stream and expose an HLS playlist through the bunnyData field.

Next steps

Set serverURL in your Payload config. Payload needs it to crop images, change the focal point and duplicate documents.

Configuration — every option, including signed URLs, thumbnails and cache purging
Examples — complete configurations for common setups
Client uploads — browser-direct uploads for serverless hosts and large files
Upgrading from v2? — the v3 config changes and data migration

Documentation

Configuration

CLI

Guides

Automatic setup

Manual setup

Next steps

​Automatic setup

​Manual setup

​Next steps

Automatic setup

Manual setup

Next steps