URL transforms

urlTransform rewrites the public URL the plugin generates for a file — add query parameters, a cache-busting timestamp, or take full control with a custom function.

payload.config.ts

bunnyStorage({
  collections: { media: true },
  storage: {/* ... */},
  urlTransform: {
    queryParams: { optimized: 'true' },
  },
})

urlTransform takes one of four forms:

false (default): no transform.
true: on a collection, use the global urlTransform. At the top level it changes nothing.
An object: appendTimestamp and queryParams.
A function: you build the URL yourself. See Custom transform function.

Simple transform

Option	Type	Default	Description
`appendTimestamp`	`boolean`	`false`	Append a `t=<timestamp>` query parameter to bust browser/CDN cache after updates.
`queryParams`	`Record<string, string>`	`{}`	Static query parameters appended to the URL.

urlTransform: {
  appendTimestamp: true,
  queryParams: {
    version: '2',
  },
}

Custom transform function

For full control, pass a function as urlTransform. It replaces appendTimestamp and queryParams — you build the URL yourself.

urlTransform: ({ baseUrl, filename }) => {
  const size = filename.includes('large') ? '600' : '300'
  return `${baseUrl}?width=${size}&quality=90`
}

The function receives:

Argument	Type	Description
`baseUrl`	`string`	The URL the plugin generated before any transform.
`collection`	`CollectionConfig`	The Payload collection config.
`filename`	`string`	The file’s base filename.
`prefix`	`string \| undefined`	The document’s own `prefix` field. It does not include the collection `prefix`.
`data`	`Record<string, unknown> \| undefined`	The document data. For Stream videos, includes `bunnyData.stream.videoId`.

Return the final URL string.

What `baseUrl` is

urlTransform runs in both access-control modes — it always rewrites the url field. What changes is the base URL it starts from, which matters when you write a transform function:

`disablePayloadAccessControl`	`baseUrl` the transform receives
`false` (default)	Payload’s own access-controlled file route, e.g. `/api/<collection>/file/<filename>`
`true`	The direct Bunny CDN URL

Collection overrides

collections: {
  avatars: {
    urlTransform: ({ baseUrl }) => `${baseUrl}?width=150&height=150`,
  },
  documents: {
    urlTransform: false, // disable transform for this collection
  },
}

A collection object merges field by field onto a global object. A collection function replaces a global object, and a collection object replaces a global function. See Collection overrides for the full list of options you can tune per collection, and Thumbnails for the equivalent transform on thumbnail URLs.

Documentation

Configuration

CLI

Guides

Simple transform

Custom transform function

What `baseUrl` is

Collection overrides

​Simple transform

​Custom transform function

​What baseUrl is

​Collection overrides

Simple transform

Custom transform function

What `baseUrl` is

Collection overrides