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

pnpm add @seshuk/payload-storage-bunny

yarn add @seshuk/payload-storage-bunny

Requires Payload CMS 3.83.0 or later and Node.js 22 or later.

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

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