feat(storage-*): large file uploads on Vercel (#11382)

Currently, usage of Payload on Vercel has a limitation - uploads are
limited by 4.5MB file size.
This PR allows you to pass `clientUploads: true` to all existing storage
adapters
* Storage S3
* Vercel Blob
* Google Cloud Storage
* Uploadthing
* Azure Blob

And then, Payload will do uploads on the client instead. With the S3
Adapter it uses signed URLs and with Vercel Blob it does this -
https://vercel.com/guides/how-to-bypass-vercel-body-size-limit-serverless-functions#step-2:-create-a-client-upload-route.
Note that it doesn't mean that anyone can now upload files to your
storage, it still does auth checks and you can customize that with
`clientUploads.access`


https://github.com/user-attachments/assets/5083c76c-8f5a-43dc-a88c-9ddc4527d91c

Implements #7569
feature request.

Author: r1tsuu

docs/upload/storage-adapters.mdx

@@ -30,6 +30,7 @@ pnpm add @payloadcms/storage-vercel-blob
 - Configure the `collections` object to specify which collections should use the Vercel Blob adapter. The slug _must_ match one of your existing collection slugs.
 - Ensure you have `BLOB_READ_WRITE_TOKEN` set in your Vercel environment variables. This is usually set by Vercel automatically after adding blob storage to your project.
 - 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.
 
 ```ts
 import { vercelBlobStorage } from '@payloadcms/storage-vercel-blob'
@@ -64,6 +65,7 @@ export default buildConfig({
 | `addRandomSuffix`    | Add a random suffix to the uploaded file name in Vercel Blob storage | `false`                       |
 | `cacheControlMaxAge` | Cache-Control max-age in seconds                                     | `365 * 24 * 60 * 60` (1 Year) |
 | `token`              | Vercel Blob storage read/write token                                 | `''`                          |
+| `clientUploads`      | Do uploads directly on the client to bypass limits on Vercel.        |                               |
 
 ## S3 Storage
 [`@payloadcms/storage-s3`](https://www.npmjs.com/package/@payloadcms/storage-s3)
@@ -79,6 +81,7 @@ pnpm add @payloadcms/storage-s3
 - Configure the `collections` object to specify which collections should use the S3 Storage adapter. The slug _must_ match one of your existing collection slugs.
 - The `config` object can be any [`S3ClientConfig`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3) object (from [`@aws-sdk/client-s3`](https://github.com/aws/aws-sdk-js-v3)). _This is highly dependent on your AWS setup_. Check the AWS documentation for more information.
 - 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 for the bucket to your website.
 
 ```ts
 import { s3Storage } from '@payloadcms/storage-s3'
@@ -126,6 +129,7 @@ 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.
 
 ```ts
 import { azureStorage } from '@payloadcms/storage-azure'
@@ -161,6 +165,7 @@ export default buildConfig({
 | `baseURL`              | Base URL for the Azure Blob storage account                              |         |
 | `connectionString`     | Azure Blob storage connection string                                     |         |
 | `containerName`        | Azure Blob storage container name                                        |         |
+| `clientUploads`        | Do uploads directly on the client to bypass limits on Vercel.            |         |
 
 ## Google Cloud Storage
 [`@payloadcms/storage-gcs`](https://www.npmjs.com/package/@payloadcms/storage-gcs)
@@ -175,6 +180,7 @@ pnpm add @payloadcms/storage-gcs
 
 - Configure the `collections` object to specify which collections should use the Google Cloud 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 for the bucket to your website.
 
 ```ts
 import { gcsStorage } from '@payloadcms/storage-gcs'
@@ -203,13 +209,14 @@ export default buildConfig({
 
 ### Configuration Options#gcs-configuration
 
-| Option        | Description                                                                                         | Default   |
-| ------------- | --------------------------------------------------------------------------------------------------- | --------- |
-| `enabled`     | Whether or not to enable the plugin                                                                 | `true`    |
-| `collections` | Collections to apply the storage to                                                                 |           |
-| `bucket`      | The name of the bucket to use                                                                       |           |
-| `options`     | Google Cloud Storage client configuration. See [Docs](https://github.com/googleapis/nodejs-storage) |           |
-| `acl`         | Access control list for files that are uploaded                                                     | `Private` |
+| Option          | Description                                                                                         | Default   |
+| --------------- | --------------------------------------------------------------------------------------------------- | --------- |
+| `enabled`       | Whether or not to enable the plugin                                                                 | `true`    |
+| `collections`   | Collections to apply the storage to                                                                 |           |
+| `bucket`        | The name of the bucket to use                                                                       |           |
+| `options`       | Google Cloud Storage client configuration. See [Docs](https://github.com/googleapis/nodejs-storage) |           |
+| `acl`           | Access control list for files that are uploaded                                                     | `Private` |
+| `clientUploads` | Do uploads directly on the client to bypass limits on Vercel.                                       |           |
 
 
 ## Uploadthing Storage
@@ -226,6 +233,7 @@ pnpm add @payloadcms/storage-uploadthing
 - Configure the `collections` object to specify which collections should use uploadthing. The slug _must_ match one of your existing collection slugs and be an `upload` type.
 - Get a token from Uploadthing and set it as `token` in the `options` object.
 - `acl` is optional and defaults to `public-read`.
+- When deploying to Vercel, server uploads are limited with 4.5MB. Set `clientUploads` to `true` to do uploads directly on the client.
 
 ```ts
 export default buildConfig({
@@ -246,13 +254,14 @@ export default buildConfig({
 
 ### Configuration Options#uploadthing-configuration
 
-| Option           | Description                                     | Default       |
-| ---------------- | ----------------------------------------------- | ------------- |
-| `token`          | Token from Uploadthing. Required.               |               |
-| `acl`            | Access control list for files that are uploaded | `public-read` |
-| `logLevel`       | Log level for Uploadthing                       | `info`        |
-| `fetch`          | Custom fetch function                           | `fetch`       |
-| `defaultKeyType` | Default key type for file operations            | `fileKey`     |
+| Option           | Description                                                   | Default       |
+| ---------------- | ------------------------------------------------------------- | ------------- |
+| `token`          | Token from Uploadthing. Required.                             |               |
+| `acl`            | Access control list for files that are uploaded               | `public-read` |
+| `logLevel`       | Log level for Uploadthing                                     | `info`        |
+| `fetch`          | Custom fetch function                                         | `fetch`       |
+| `defaultKeyType` | Default key type for file operations                          | `fileKey`     |
+| `clientUploads`  | Do uploads directly on the client to bypass limits on Vercel. |               |
 
 
 ## Custom Storage Adapters

packages/payload/src/uploads/types.ts

@@ -178,7 +178,7 @@ export type UploadConfig = {
     req: PayloadRequest,
     args: {
       doc: TypeWithID
-      params: { collection: string; filename: string }
+      params: { clientUploadContext?: unknown; collection: string; filename: string }
     },
   ) => Promise<Response> | Promise<void> | Response | void)[]
   /**

packages/payload/src/utilities/addDataAndFileToRequest.ts

@@ -44,6 +44,54 @@ export const addDataAndFileToRequest: AddDataAndFileToRequest = async (req) => {
       if (fields?._payload && typeof fields._payload === 'string') {
         req.data = JSON.parse(fields._payload)
       }
+
+      if (!req.file && fields?.file && typeof fields?.file === 'string') {
+        const { clientUploadContext, collectionSlug, filename, mimeType, size } = JSON.parse(
+          fields.file,
+        )
+        const uploadConfig = req.payload.collections[collectionSlug].config.upload
+
+        if (!uploadConfig.handlers) {
+          throw new APIError('uploadConfig.handlers is not present for ' + collectionSlug)
+        }
+
+        let response: null | Response = null
+        let error: unknown
+
+        for (const handler of uploadConfig.handlers) {
+          try {
+            const result = await handler(req, {
+              doc: null,
+              params: {
+                clientUploadContext, // Pass additional specific to adapters context returned from UploadHandler, then staticHandler can use them.
+                collection: collectionSlug,
+                filename,
+              },
+            })
+            if (result) {
+              response = result
+            }
+            // If we couldn't get the file from that handler, save the error and try other.
+          } catch (err) {
+            error = err
+          }
+        }
+
+        if (!response) {
+          if (error) {
+            payload.logger.error(error)
+          }
+
+          throw new APIError('Expected response from the upload handler.')
+        }
+
+        req.file = {
+          name: filename,
+          data: Buffer.from(await response.arrayBuffer()),
+          mimetype: response.headers.get('Content-Type') || mimeType,
+          size,
+        }
+      }
     }
   }
 }

packages/plugin-cloud-storage/.swcrc

@@ -7,6 +7,15 @@
       "syntax": "typescript",
       "tsx": true,
       "dts": true
+    },
+    "transform": {
+      "react": {
+        "runtime": "automatic",
+        "pragmaFrag": "React.Fragment",
+        "throwIfNamespace": true,
+        "development": false,
+        "useBuiltins": true
+      }
     }
   },
   "module": {

packages/plugin-cloud-storage/package.json

@@ -33,6 +33,11 @@
       "import": "./src/exports/utilities.ts",
       "types": "./src/exports/utilities.ts",
       "default": "./src/exports/utilities.ts"
+    },
+    "./client": {
+      "import": "./src/exports/client.ts",
+      "types": "./src/exports/client.ts",
+      "default": "./src/exports/client.ts"
     }
   },
   "main": "./src/index.ts",
@@ -53,15 +58,20 @@
     "test": "echo \"No tests available.\""
   },
   "dependencies": {
+    "@payloadcms/ui": "workspace:*",
     "find-node-modules": "^2.1.3",
     "range-parser": "^1.2.1"
   },
   "devDependencies": {
     "@types/find-node-modules": "^2.1.2",
+    "@types/react": "19.0.1",
+    "@types/react-dom": "19.0.1",
     "payload": "workspace:*"
   },
   "peerDependencies": {
-    "payload": "workspace:*"
+    "payload": "workspace:*",
+    "react": "^19.0.0 || ^19.0.0-rc-65a56d0e-20241020",
+    "react-dom": "^19.0.0 || ^19.0.0-rc-65a56d0e-20241020"
   },
   "publishConfig": {
     "exports": {
@@ -79,6 +89,11 @@
         "import": "./dist/exports/utilities.js",
         "types": "./dist/exports/utilities.d.ts",
         "default": "./dist/exports/utilities.js"
+      },
+      "./client": {
+        "import": "./dist/exports/client.js",
+        "types": "./dist/exports/client.d.ts",
+        "default": "./dist/exports/client.js"
       }
     },
     "main": "./dist/index.js",

packages/plugin-cloud-storage/src/client/createClientUploadHandler.tsx

@@ -0,0 +1,69 @@
+'use client'
+
+import type { UploadCollectionSlug } from 'payload'
+
+import { useConfig, useEffectEvent, useUploadHandlers } from '@payloadcms/ui'
+import { Fragment, type ReactNode, useEffect } from 'react'
+
+type ClientUploadHandlerProps<T extends Record<string, unknown>> = {
+  children: ReactNode
+  collectionSlug: UploadCollectionSlug
+  enabled?: boolean
+  extra: T
+  serverHandlerPath: string
+}
+
+export const createClientUploadHandler = <T extends Record<string, unknown>>({
+  handler,
+}: {
+  handler: (args: {
+    apiRoute: string
+    collectionSlug: UploadCollectionSlug
+    extra: T
+    file: File
+    serverHandlerPath: string
+    serverURL: string
+    updateFilename: (value: string) => void
+  }) => Promise<unknown>
+}) => {
+  return function ClientUploadHandler({
+    children,
+    collectionSlug,
+    enabled,
+    extra,
+    serverHandlerPath,
+  }: ClientUploadHandlerProps<T>) {
+    const { setUploadHandler } = useUploadHandlers()
+    const {
+      config: {
+        routes: { api: apiRoute },
+        serverURL,
+      },
+    } = useConfig()
+
+    const initializeHandler = useEffectEvent(() => {
+      if (enabled) {
+        setUploadHandler({
+          collectionSlug,
+          handler: ({ file, updateFilename }) => {
+            return handler({
+              apiRoute,
+              collectionSlug,
+              extra,
+              file,
+              serverHandlerPath,
+              serverURL,
+              updateFilename,
+            })
+          },
+        })
+      }
+    })
+
+    useEffect(() => {
+      initializeHandler()
+    }, [])
+
+    return <Fragment>{children}</Fragment>
+  }
+}

packages/plugin-cloud-storage/src/exports/client.ts

@@ -0,0 +1 @@
+export { createClientUploadHandler } from '../client/createClientUploadHandler.js'

packages/plugin-cloud-storage/src/exports/utilities.ts

@@ -1 +1,2 @@
 export { getFilePrefix } from '../utilities/getFilePrefix.js'
+export { initClientUploads } from '../utilities/initClientUploads.js'

packages/plugin-cloud-storage/src/types.ts

@@ -16,6 +16,17 @@ export interface File {
   tempFilePath?: string
 }
 
+export type ClientUploadsAccess = (args: {
+  collectionSlug: UploadCollectionSlug
+  req: PayloadRequest
+}) => boolean | Promise<boolean>
+
+export type ClientUploadsConfig =
+  | {
+      access?: ClientUploadsAccess
+    }
+  | boolean
+
 export type HandleUpload = (args: {
   collection: CollectionConfig
   data: any
@@ -43,7 +54,10 @@ export type GenerateURL = (args: {
 
 export type StaticHandler = (
   req: PayloadRequest,
-  args: { doc?: TypeWithID; params: { collection: string; filename: string } },
+  args: {
+    doc?: TypeWithID
+    params: { clientUploadContext?: unknown; collection: string; filename: string }
+  },
 ) => Promise<Response> | Response
 
 export interface GeneratedAdapter {