feat(storage-vercel-blob): add allowOverwrite option

[joeliomartini]

Summary

Adds a new allowOverwrite option to VercelBlobStorageOptions that passes through to all @vercel/blob put() calls — both server-side uploads (handleUpload.ts) and client upload token generation (getClientUploadRoute.ts).

Problem

When using clientUploads: true with addRandomSuffix: false, failed uploads leave orphan blobs in Vercel Blob storage. The blob is created successfully, but Payload's server-side processing (image size generation, generateFileData) can fail with a 400 error — leaving a blob without a corresponding Payload media record.

Subsequent uploads of the same filename then fail with:

Vercel Blob: This blob already exists, use allowOverwrite: true if you want to overwrite it.

This is particularly frustrating because the user has no way to clean up the orphan blob through the Payload admin — the media record was never created, so there's nothing to delete.

Related: #14709

Solution

The @vercel/blob SDK already supports allowOverwrite: true on put() calls, but the Payload adapter didn't expose this option. This PR adds it as a top-level config option:

vercelBlobStorage({
  token: process.env.BLOB_READ_WRITE_TOKEN,
  collections: { media: true },
  allowOverwrite: true, // new option
})

Changes

• index.ts: Added allowOverwrite to VercelBlobStorageOptions type with JSDoc documentation. Passes it through to both getHandleUpload and getClientUploadRoute.
• handleUpload.ts: Passes allowOverwrite to the put() call for server-side uploads.
• getClientUploadRoute.ts: Passes allowOverwrite in the onBeforeGenerateToken return value for client-side uploads.

Default behavior

allowOverwrite defaults to false, preserving the current behavior. No breaking changes.

[rchlfryn]

+1

Nice work — this is exactly what we need. We're currently carrying a local pnpm patch with the same changes.

One thing I noticed: the extraClientHandlerProps callback in index.ts doesn't pass allowOverwrite through to the client handler, and VercelBlobClientUploadHandler.ts doesn't destructure it from extra. This means client-side uploads (clientUploads: true) won't respect the option — only server-side uploads will.

The fix would be two additions:

src/index.ts — in extraClientHandlerProps:

extraClientHandlerProps: (collection) => ({
  addRandomSuffix: !!optionsWithDefaults.addRandomSuffix,
  allowOverwrite: !!optionsWithDefaults.allowOverwrite, // add this
  baseURL: baseUrl,
  prefix: ...
}),

src/client/VercelBlobClientUploadHandler.ts — destructure from extra and add to the type:

extra: { addRandomSuffix, allowOverwrite, baseURL, prefix = '' },

The allowOverwrite value flows through the client token via onBeforeGenerateToken (which your PR already handles), so the client upload() call doesn't need it directly — but the type and destructuring should be consistent with addRandomSuffix.

[joeliomartini]

Thanks for catching that @rchlfryn — great eye. Just pushed a fix that adds allowOverwrite to extraClientHandlerProps and the VercelBlobClientUploadHandler type + destructuring.

Good to know you're carrying the same patch locally — hopefully this gets merged soon so we can all drop it!