> ## Documentation Index
> Fetch the complete documentation index at: https://payload-storage-bunny.seshuk.im/llms.txt
> Use this file to discover all available pages before exploring further.

# URL transforms

> Rewrite the public URLs the plugin generates with query params, cache-busting timestamps, or a custom function.

`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.

```ts payload.config.ts theme={null}
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](#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. |

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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](/v4/configuration/collection-overrides) for the full list of options you can tune per collection, and [Thumbnails](/v4/configuration/thumbnails) for the equivalent transform on thumbnail URLs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.