Upgrade guide

​

v3.1.1 to v3.1.2

• tus-auth checks the file like a storage client upload. It rejects a type outside the collection’s upload.mimeTypes or the Stream mimeTypes, a restricted type and a file over upload.limits.fileSize, even when checkAccess allows the request. The saved document gets the signed file size and MIME type.
• A videoToken is bound to the signed-in user and expires after 24 hours. Tokens from v3.1.1 stop working, so an upload that was paused before the update starts again. The same happens to an upload that stays paused for more than 24 hours.
• Payload rejects a videoId that another document in a Stream collection of the same library already uses.

​

v3.1.0 to v3.1.1

const { docs } = await payload.find({
  collection: 'media',
  overrideAccess: true,
  where: {
    or: [{ prefix: { equals: '' } }, { prefix: { exists: false } }],
  },
})

​

v3.0.x to v3.1.0

​

1. Install the cloud storage plugin

pnpm add @payloadcms/plugin-cloud-storage

​

2. Redeploy the Edge Script

npx payload bunny:deploy-edge-script

​

3. Stricter client uploads

• Without a custom clientUploads.access function, the user needs create or update access to the collection.
• filesize is required, next to collectionSlug, filename and mimeType.
• HTML, JavaScript, SVG and XML files are rejected, unless the collection sets upload.allowRestrictedFileTypes: true.
• The upload URL only accepts the declared size and MIME type.
• It returns 409 when a file already exists at the path.

​

4. Custom upload clients

• Client uploads. Send the headers from the upload endpoint response with the PUT. Send the clientUploadContext from the same response unchanged with the document. Payload now requires its signed receipt, and the plugin takes the prefix, file size and MIME type from it.
• TUS and Stream. tus-auth returns a videoToken with every videoId. Send it as bunnyData.stream.videoToken when you save a document with a videoId, and send videoId with videoToken to resume an upload. Without a valid token, Payload ignores the videoId on save, and tus-auth creates a new video.
• Stream client uploads. Send the file head as head to tus-auth, and send the returned clientUploadContext unchanged with the document.
• Read-only fields. The injected prefix field and bunnyData.stream.resolutions no longer accept values from the REST or GraphQL API. Server code that uses the Local API is not affected.

​

5. Check static plus mint-time prefixes

​

v2.x to v3.0

​

Config changes (breaking)

• Client uploads — browser-direct uploads, configured under storage.clientUploads (storage.clientUploads: true shorthand, or the full config). There is no mode option — the transport is chosen automatically (presigned S3 when the zone sets storage.s3, otherwise a deployed Edge Script).
• Per-collection zones and libraries — point a collection at its own storage zone / stream library with a full config; the top-level storage/stream become optional.
• storage.s3 — S3-compatible zone access.
• stream.referer — Referer header for MP4-fallback requests behind BlockNoneReferrer libraries.
• Per-collection stream.tus: false — disable TUS for one collection.
• Stream webhook (stream.webhook) — v2 had no webhook; MP4-fallback resolutions were fetched lazily on the first serve (v3 still does this as a fallback). The optional webhook pre-populates bunnyData.stream.resolutions the moment encoding finishes instead. Set webhook.secret to the library’s Read-Only API key (Bunny signs each callback with the X-BunnyStream-Signature HMAC header) and point your Bunny library’s webhook at /api/storage-bunny/stream/webhook.

​

What changed (data)

​

Migrate your data

npm install @seshuk/payload-storage-bunny@latest

pnpm add @seshuk/payload-storage-bunny@latest

yarn add @seshuk/payload-storage-bunny@latest

npx payload migrate:create bunny_v3

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

export async function up({ payload, req }) {
  await migrateBunnyData({ payload, req })
}

export async function down({ payload, req }) {
  await migrateBunnyData({ payload, req, direction: 'rollback' })
}

npx payload migrate

await migrateBunnyData({ payload, req, drop: true })

export async function up({ payload, req }) {
  await migrateBunnyData({ payload, req, drop: true }) // migrate, then drop the legacy fields/columns
}

​

Database notes

​

Options

​

v2.1.x to v2.2.0

​

What changed

1. Move purge.apiKey to plugin-level apiKey (old way still works but deprecated)
2. Replace adminThumbnail with thumbnail (required, no backward compatibility)
3. Optionally use new collection overrides for storage.uploadTimeout, stream.uploadTimeout, stream.mp4Fallback, stream.tus.uploadTimeout

​

v2.0.x to v2.1.0

​

What changed

​

v1.x to v2.x

​

Version requirements

​

What changed

​

How to migrate

npm install @seshuk/payload-storage-bunny@latest

pnpm add @seshuk/payload-storage-bunny@latest

yarn add @seshuk/payload-storage-bunny@latest

bunnyStorage({
  collections: {/* ... */},
  options: {
    // Remove this
    storage: {/* ... */},
    stream: {/* ... */},
    purge: {/* ... */},
  },
})

bunnyStorage({
  collections: {/* ... */},
  storage: {/* ... */}, // Move to top level
  stream: {/* ... */},
  purge: {/* ... */},
})

stream: {
  libraryId: '123456',           // String
  mp4Fallback: { enabled: true } // Object
}

stream: {
  libraryId: 123456,    // Number
  mp4Fallback: true     // Boolean
}

purge: {
  enabled: true,  // Remove this
  apiKey: '...'
}

purge: {
  apiKey: '...' // Presence enables it
}

// Remove this entirely:
experimental: {
  replaceSaveButtonComponent: true
}

​

Complete example

bunnyStorage({
  collections: {
    media: {
      prefix: 'uploads',
      disablePayloadAccessControl: true,
    },
  },
  options: {
    // Remove wrapper
    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', // String
      mp4Fallback: { enabled: true }, // Object
      thumbnailTime: 5000,
    },
    purge: {
      enabled: true, // Remove
      apiKey: process.env.BUNNY_API_KEY,
    },
  },
  experimental: {
    // Remove
    replaceSaveButtonComponent: true,
  },
})

bunnyStorage({
  collections: {
    media: {
      prefix: 'uploads',
      disablePayloadAccessControl: true,
    },
  },
  storage: {
    // No wrapper
    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, // Number
    mp4Fallback: true, // Boolean
    thumbnailTime: 5000,
    // New features you can add:
    tus: true,
    cleanup: true,
  },
  purge: {
    apiKey: process.env.BUNNY_API_KEY, // No `enabled`
  },
})

​

New features in v2.x

stream: {
  tus: true, // Simple setup
  // Or customize:
  tus: {
    autoMode: true, // Auto-enable for video files
    uploadTimeout: 7200
  }
}

signedUrls: {
  expiresIn: 7200,
  allowedCountries: ['US', 'ID'],
  staticHandler: { useRedirect: true }
}

urlTransform: {
  queryParams: {
    source: 'app'
  }
  // Or custom function:
  // transformUrl: ({ baseUrl, filename }) => `${baseUrl}/${filename}?custom`
}

thumbnail: {
  appendTimestamp: true, // Default in v2.x
  queryParams: { w: '300', h: '300' }
}

stream: {
  cleanup: true // Runs daily cleanup
}

​

Need help?