Cache purge

The CDN caches your files at edge locations around the world. When you replace a file, visitors might still see the old cached copy. purge tells Bunny to invalidate the cached copy immediately after every upload and delete.

payload.config.ts

bunnyStorage({
  accountApiKey: process.env.BUNNY_ACCOUNT_API_KEY, // required for purge
  collections: { media: true },
  storage: {/* ... */},
  purge: true, // enable with defaults
})

Options

Option	Type	Default	Description
`async`	`boolean`	`false`	If `true`, the upload/delete request doesn’t wait for the purge to finish.

Pass purge: true for defaults, purge: false to disable, or an object to customize:

purge: {
  async: true,
}

The plugin purges the plain CDN URL of the file with a trailing *, so Bunny also clears cached copies with query strings, such as signed or transformed URLs.

Requirements

Cache purging is an account-level operation, so it needs a Bunny account API key (not the Storage or Stream key) at the top level, as accountApiKey. Get it from your Bunny dashboard → account menu (top-right) → Account settings → API → copy the API key.

Without a global accountApiKey, the options validator throws a startup error, including when only individual collections enable purge.Purging is only performed for Bunny Storage files — it doesn’t apply to Stream videos, which are served from Bunny’s video CDN and cached differently.

Alternative: timestamp-based cache busting

If you don’t want to manage an account API key, urlTransform.appendTimestamp or thumbnail.urlTransform.appendTimestamp add a changing query parameter to URLs instead. This is simpler to set up, but only busts the cache for browsers that re-fetch the URL — it doesn’t proactively clear Bunny’s edge cache.

Approach	Setup	Effect
Cache purging (`purge`)	Needs `accountApiKey`	Immediate, global invalidation on every change
Timestamp busting (`appendTimestamp`)	No extra credentials	Only helps once a client re-requests the (now different) URL

Collection overrides

collections: {
  images: {
    purge: false, // disable purging for this collection
  },
  documents: {
    purge: {
      async: true, // override async for this collection
    },
  },
  archive: {
    purge: true, // works even when the global purge is off
  },
}

purge: true on a collection uses the global purge settings. See Collection overrides for the full list of options you can tune per collection.

Documentation

Configuration

CLI

Guides

Options

Requirements

Alternative: timestamp-based cache busting

Collection overrides

​Options

​Requirements

​Alternative: timestamp-based cache busting

​Collection overrides

Options

Requirements

Alternative: timestamp-based cache busting

Collection overrides