feat(storage-azure): client uploads with chunkLargeFiles can now support files larger than 5gb (#17319)

v3 port of #17318

In v4 this is enabled by default, in v3 this is behind a flag because
it's potentially breaking as CORS needs additional headers setup.

## What

Adds opt-in support for uploading files larger than ~5GB directly from
the client with the Azure storage adapter. A new
`clientUploads.chunkLargeFiles` option routes browser uploads through
the Azure Blob SDK, which splits the file into blocks instead of sending
it in a single request.

## Why

Client uploads (`clientUploads: true`) previously sent each file to
Azure in one `Put Blob` request. Azure caps a single `Put Blob` at ~5GB,
so any larger file failed outright — which defeats the purpose of client
uploads, since they exist specifically to move large files that can't go
through the server/proxy body limits.

The Blob SDK's block API (`Put Block` + `Put Block List`) is Azure's
supported path for large blobs. It splits the file into blocks, uploads
them in parallel, and commits at the end, raising the effective ceiling
to the block-blob maximum (~190TiB) while also improving throughput on
large transfers.

## Behaviour

- **Default is unchanged.** With `clientUploads: true`, uploads still
use the original single-request path and the same CORS requirements.
Existing setups behave exactly as before — this is not a breaking
change.
- **Large-file support is opt-in.** Set `clientUploads: {
chunkLargeFiles: true }` to switch to the SDK block-upload path for
files over ~5GB.

```ts
azureStorage({
  clientUploads: {
    chunkLargeFiles: true,
  },
  // ...
})
```

`chunkLargeFiles` routes client uploads through the Azure Blob SDK,
which sends extra `x-ms-*` headers and issues CORS preflight (OPTIONS)
requests.

The storage account's CORS rules must therefore allow:
 - Methods: OPTIONS, PUT (GET/HEAD too if reading blobs in-browser)
- Allowed headers: `*` (or at minimum
`x-ms-*,content-type,content-length`)
 - Exposed headers: `*`

Without these, block uploads fail in the browser with "RestError: Failed
to fetch".

Author: paulpopus

docs/upload/storage-adapters.mdx

@@ -8,8 +8,8 @@ keywords: uploads, images, media, storage, adapters, s3, vercel, google cloud, a
 
 Payload offers additional storage adapters to handle file uploads. These adapters allow you to store files in different locations, such as Amazon S3, Vercel Blob Storage, Google Cloud Storage, and more.
 
-| Service              | Package                                                                                                           |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Service              | Package                                                                                                          |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | Vercel Blob          | [`@payloadcms/storage-vercel-blob`](https://github.com/payloadcms/payload/tree/3.x/packages/storage-vercel-blob) |
 | AWS S3               | [`@payloadcms/storage-s3`](https://github.com/payloadcms/payload/tree/3.x/packages/storage-s3)                   |
 | Azure                | [`@payloadcms/storage-azure`](https://github.com/payloadcms/payload/tree/3.x/packages/storage-azure)             |
@@ -216,7 +216,26 @@ pnpm add @payloadcms/storage-azure
 
 - Configure the `collections` object to specify which collections should use the Azure Blob adapter. The slug _must_ match one of your existing collection slugs.
 - When enabled, this package will automatically set `disableLocalStorage` to `true` for each collection.
-- When deploying to Vercel, server uploads are limited with 4.5MB. Set `clientUploads` to `true` to do uploads directly on the client. You must allow CORS PUT method to your website.
+- When deploying to Vercel, server uploads are limited with 4.5MB. Set `clientUploads` to `true` to do uploads directly on the client.
+
+- Client uploads send each file in a single request, which Azure caps at ~5GB. To upload larger files, set `clientUploads: { chunkLargeFiles: true }` — this uploads through the Azure Blob SDK, which splits the file into blocks and raises the limit to Azure's block-blob maximum.
+
+<Banner type="warning">
+  **`chunkLargeFiles` and CORS:** With `chunkLargeFiles: true`, the Azure Blob SDK
+  sends additional `x-ms-*` headers, so the browser issues a CORS preflight. Your
+  storage account's CORS rules must allow the `OPTIONS` and `PUT` methods **and**
+  those headers. Configure a CORS rule on the Blob service (Storage account →
+  **Resource sharing (CORS)**):
+
+| Field           | Value                                                    |
+| --------------- | -------------------------------------------------------- |
+| Allowed origins | Your site origin (e.g. `https://example.com`)            |
+| Allowed methods | `GET,PUT,OPTIONS` (`HEAD` if reading in-browser)         |
+| Allowed headers | `*` (or at minimum `x-ms-*,content-type,content-length`) |
+| Exposed headers | `*`                                                      |
+| Max age         | `3600`                                                   |
+
+</Banner>
 
 ```ts
 import { azureStorage } from '@payloadcms/storage-azure'
@@ -452,13 +471,13 @@ This plugin is configurable to work across many different Payload collections. A
 
 ## Collection-specific options
 
-| Option                        | Type                                                                                                              | Description                                                                                                                                                                                                   |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Option                        | Type                                                                                                             | Description                                                                                                                                                                                                   |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `adapter` \*                  | [Adapter](https://github.com/payloadcms/payload/blob/3.x/packages/plugin-cloud-storage/src/types.ts#L49)         | Pass in the adapter that you'd like to use for this collection. You can also set this field to `null` for local development if you'd like to bypass cloud storage in certain scenarios and use local storage. |
-| `disableLocalStorage`         | `boolean`                                                                                                         | Choose to disable local storage on this collection. Defaults to `true`.                                                                                                                                       |
-| `disablePayloadAccessControl` | `true`                                                                                                            | Set to `true` to disable Payload's Access Control. [More](#payload-access-control)                                                                                                                            |
+| `disableLocalStorage`         | `boolean`                                                                                                        | Choose to disable local storage on this collection. Defaults to `true`.                                                                                                                                       |
+| `disablePayloadAccessControl` | `true`                                                                                                           | Set to `true` to disable Payload's Access Control. [More](#payload-access-control)                                                                                                                            |
 | `generateFileURL`             | [GenerateFileURL](https://github.com/payloadcms/payload/blob/3.x/packages/plugin-cloud-storage/src/types.ts#L67) | Override the generated file URL with one that you create.                                                                                                                                                     |
-| `prefix`                      | `string`                                                                                                          | Set to `media/images` to upload files inside `media/images` folder in the bucket.                                                                                                                             |
+| `prefix`                      | `string`                                                                                                         | Set to `media/images` to upload files inside `media/images` folder in the bucket.                                                                                                                             |
 
 ## Prefix Composition
 

packages/storage-azure/README.md

@@ -14,7 +14,32 @@ pnpm add @payloadcms/storage-azure
 
 - Configure the `collections` object to specify which collections should use the Azure Blob Storage adapter. The slug _must_ match one of your existing collection slugs.
 - When enabled, this package will automatically set `disableLocalStorage` to `true` for each collection.
-- When deploying to Vercel, server uploads are limited with 4.5MB. Set `clientUploads` to `true` to do uploads directly on the client. You must allow CORS PUT method to your website.
+- When deploying to Vercel, server uploads are limited with 4.5MB. Set `clientUploads` to `true` to do uploads directly on the client.
+
+### Large client uploads (files over ~5GB)
+
+By default, client uploads (`clientUploads: true`) send each file in a single request, which Azure caps at ~5GB. To upload larger files, set `chunkLargeFiles: true`:
+
+```ts
+azureStorage({
+  // ...
+  clientUploads: {
+    chunkLargeFiles: true,
+  },
+})
+```
+
+This uploads through the Azure Blob SDK, which splits the file into blocks (`Put Block` + `Put Block List`) and raises the limit to Azure's block-blob maximum (~190TiB).
+
+Because the SDK sends additional `x-ms-*` headers, the browser issues a CORS preflight, so your storage account's CORS rules must allow the `OPTIONS` and `PUT` methods **and** those headers. Configure a CORS rule on the Blob service (Storage account → **Resource sharing (CORS)**):
+
+| Field           | Value                                                    |
+| --------------- | -------------------------------------------------------- |
+| Allowed origins | Your site origin (e.g. `https://example.com`)            |
+| Allowed methods | `GET,PUT,OPTIONS` (add `HEAD` if reading in-browser)     |
+| Allowed headers | `*` (or at minimum `x-ms-*,content-type,content-length`) |
+| Exposed headers | `*`                                                      |
+| Max age         | `3600`                                                   |
 
 ```ts
 import { azureStorage } from '@payloadcms/storage-azure'

packages/storage-azure/src/client/AzureClientUploadHandler.ts

@@ -1,58 +1,32 @@
 'use client'
 import { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/client'
-import { formatAdminURL } from 'payload/shared'
 
-export const AzureClientUploadHandler = createClientUploadHandler({
+import { handleAzureUpload } from './handleAzureUpload.js'
+
+export type AzureClientUploadHandlerExtra = {
+  chunkLargeFiles: boolean
+}
+
+export const AzureClientUploadHandler = createClientUploadHandler<AzureClientUploadHandlerExtra>({
   handler: async ({
     apiRoute,
     collectionSlug,
     docPrefix,
+    extra: { chunkLargeFiles },
     file,
     serverHandlerPath,
     serverURL,
     updateFilename,
   }) => {
-    const endpointRoute = formatAdminURL({
+    return handleAzureUpload({
       apiRoute,
-      path: serverHandlerPath,
+      chunkLargeFiles,
+      collectionSlug,
+      docPrefix,
+      file,
+      serverHandlerPath,
       serverURL,
+      updateFilename,
     })
-    const response = await fetch(endpointRoute, {
-      body: JSON.stringify({
-        collectionSlug,
-        docPrefix,
-        filename: file.name,
-        mimeType: file.type,
-      }),
-      credentials: 'include',
-      method: 'POST',
-    })
-
-    const {
-      docPrefix: sanitizedDocPrefix,
-      filename: sanitizedFilename,
-      url,
-    } = (await response.json()) as {
-      docPrefix: string
-      filename?: string
-      url: string
-    }
-
-    if (sanitizedFilename && sanitizedFilename !== file.name) {
-      updateFilename(sanitizedFilename)
-    }
-
-    await fetch(url, {
-      body: file,
-      headers: {
-        'Content-Length': file.size.toString(),
-        'Content-Type': file.type,
-        // Required for azure
-        'x-ms-blob-type': 'BlockBlob',
-      },
-      method: 'PUT',
-    })
-
-    return { prefix: sanitizedDocPrefix }
   },
 })

packages/storage-azure/src/client/handleAzureUpload.spec.ts

@@ -0,0 +1,164 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const uploadDataMock = vi.fn()
+const blockBlobClientMock = vi.fn(function () {
+  return { uploadData: uploadDataMock }
+})
+
+vi.mock('@azure/storage-blob', () => ({
+  BlockBlobClient: blockBlobClientMock,
+}))
+
+import { handleAzureUpload } from './handleAzureUpload.js'
+
+const serverURL = 'https://example.com'
+const apiRoute = '/api'
+const serverHandlerPath = '/storage-azure-generate-signed-url' as const
+const signedURL = 'https://account.blob.core.windows.net/container/file.png?sig=abc'
+
+const createFile = () => new File([new Uint8Array([1, 2, 3])], 'file.png', { type: 'image/png' })
+
+const mockSignedURLResponse = (body: Record<string, unknown>, ok = true) => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    json: () => Promise.resolve(body),
+    ok,
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+const invoke = (overrides: Partial<Parameters<typeof handleAzureUpload>[0]> = {}) =>
+  handleAzureUpload({
+    apiRoute,
+    chunkLargeFiles: true,
+    collectionSlug: 'media',
+    file: createFile(),
+    serverHandlerPath,
+    serverURL,
+    updateFilename: vi.fn(),
+    ...overrides,
+  })
+
+describe('handleAzureUpload', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.unstubAllGlobals()
+    uploadDataMock.mockResolvedValue(undefined)
+  })
+
+  describe('shared behavior', () => {
+    it('should request a signed URL from the server handler', async () => {
+      const fetchMock = mockSignedURLResponse({ docPrefix: 'docs', url: signedURL })
+
+      await invoke({ docPrefix: 'docs' })
+
+      const [calledURL, init] = fetchMock.mock.calls[0]!
+      expect(calledURL).toBe(`${serverURL}${apiRoute}${serverHandlerPath}`)
+      expect(init.method).toBe('POST')
+      expect(JSON.parse(init.body)).toEqual({
+        collectionSlug: 'media',
+        docPrefix: 'docs',
+        filename: 'file.png',
+        mimeType: 'image/png',
+      })
+    })
+
+    it('should call updateFilename when the server returns a sanitized filename', async () => {
+      mockSignedURLResponse({ docPrefix: 'docs', filename: 'file-1.png', url: signedURL })
+      const updateFilename = vi.fn()
+
+      await invoke({ updateFilename })
+
+      expect(updateFilename).toHaveBeenCalledWith('file-1.png')
+    })
+
+    it('should not call updateFilename when the filename is unchanged', async () => {
+      mockSignedURLResponse({ docPrefix: 'docs', filename: 'file.png', url: signedURL })
+      const updateFilename = vi.fn()
+
+      await invoke({ updateFilename })
+
+      expect(updateFilename).not.toHaveBeenCalled()
+    })
+
+    it('should return the sanitized doc prefix', async () => {
+      mockSignedURLResponse({ docPrefix: 'sanitized-docs', url: signedURL })
+
+      const result = await invoke()
+
+      expect(result).toEqual({ prefix: 'sanitized-docs' })
+    })
+
+    it('should throw when the signed URL request fails, before any upload', async () => {
+      mockSignedURLResponse({}, false)
+
+      await expect(invoke()).rejects.toThrow()
+
+      expect(uploadDataMock).not.toHaveBeenCalled()
+      expect(blockBlobClientMock).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('chunkLargeFiles: true (SDK block upload)', () => {
+    it('should upload via BlockBlobClient.uploadData rather than a raw PUT', async () => {
+      const fetchMock = mockSignedURLResponse({ docPrefix: 'docs', url: signedURL })
+      const file = createFile()
+
+      await invoke({ chunkLargeFiles: true, file })
+
+      expect(blockBlobClientMock).toHaveBeenCalledWith(signedURL)
+      expect(uploadDataMock).toHaveBeenCalledTimes(1)
+
+      const [uploadedFile, options] = uploadDataMock.mock.calls[0]!
+      expect(uploadedFile).toBe(file)
+      expect(options.blockSize).toBeGreaterThan(0)
+      expect(options.concurrency).toBeGreaterThan(0)
+
+      // Only the signed-URL request should hit fetch; no raw PUT to the blob URL.
+      expect(fetchMock).toHaveBeenCalledTimes(1)
+    })
+
+    it('should pass the file content type to the blob headers', async () => {
+      mockSignedURLResponse({ docPrefix: 'docs', url: signedURL })
+
+      await invoke({ chunkLargeFiles: true })
+
+      const [, options] = uploadDataMock.mock.calls[0]!
+      expect(options.blobHTTPHeaders).toEqual({ blobContentType: 'image/png' })
+    })
+
+    it('should propagate errors from uploadData', async () => {
+      mockSignedURLResponse({ docPrefix: 'docs', url: signedURL })
+      uploadDataMock.mockRejectedValue(new Error('block upload failed'))
+
+      await expect(invoke({ chunkLargeFiles: true })).rejects.toThrow('block upload failed')
+    })
+  })
+
+  describe('chunkLargeFiles: false (single PUT, default/legacy)', () => {
+    it('should upload via a single raw PUT with the BlockBlob header', async () => {
+      const fetchMock = mockSignedURLResponse({ docPrefix: 'docs', url: signedURL })
+      const file = createFile()
+
+      await invoke({ chunkLargeFiles: false, file })
+
+      // 1st fetch = signed-URL POST, 2nd = the raw PUT to the blob URL
+      expect(fetchMock).toHaveBeenCalledTimes(2)
+      const [putURL, putInit] = fetchMock.mock.calls[1]!
+      expect(putURL).toBe(signedURL)
+      expect(putInit.method).toBe('PUT')
+      expect(putInit.body).toBe(file)
+      expect(putInit.headers['x-ms-blob-type']).toBe('BlockBlob')
+      expect(putInit.headers['Content-Type']).toBe('image/png')
+    })
+
+    it('should not use the Azure SDK', async () => {
+      mockSignedURLResponse({ docPrefix: 'docs', url: signedURL })
+
+      await invoke({ chunkLargeFiles: false })
+
+      expect(blockBlobClientMock).not.toHaveBeenCalled()
+      expect(uploadDataMock).not.toHaveBeenCalled()
+    })
+  })
+})