Storage Adapters

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
Vercel Blob	`@payloadcms/storage-vercel-blob`
AWS S3	`@payloadcms/storage-s3`
Azure	`@payloadcms/storage-azure`
Google Cloud Storage	`@payloadcms/storage-gcs`
Uploadthing	`@payloadcms/storage-uploadthing`

Vercel Blob Storage

@payloadcms/storage-vercel-blob

Installation

1pnpm add @payloadcms/storage-vercel-blob

Usage

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.

1import { vercelBlobStorage } from '@payloadcms/storage-vercel-blob'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
plugins: [
  vercelBlobStorage({
    enabled: true, // Optional, defaults to true
    // Specify which collections should use Vercel Blob
    collections: {
      media: true,
      'media-with-prefix': {
        prefix: 'my-prefix',
      },
    },
    // Token provided by Vercel once Blob storage is added to your Vercel project
    token: process.env.BLOB_READ_WRITE_TOKEN,
  }),
],
21})

Configuration Options

Option	Description	Default
`enabled`	Whether or not to enable the plugin	`true`
`collections`	Collections to apply the Vercel Blob adapter to
`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

Installation

1pnpm add @payloadcms/storage-s3

Usage

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 object (from @aws-sdk/client-s3). 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.

1import { s3Storage } from '@payloadcms/storage-s3'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
plugins: [
  s3Storage({
    collections: {
      media: true,
      'media-with-prefix': {
        prefix,
      },
    },
    bucket: process.env.S3_BUCKET,
    config: {
      credentials: {
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
      },
      region: process.env.S3_REGION,
      // ... Other S3 configuration
    },
  }),
],
26})

Configuration Options

See the the AWS SDK Package and S3ClientConfig object for guidance on AWS S3 configuration.

Azure Blob Storage

@payloadcms/storage-azure

Installation

1pnpm add @payloadcms/storage-azure

Usage

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.

1import { azureStorage } from '@payloadcms/storage-azure'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
plugins: [
  azureStorage({
    collections: {
      media: true,
      'media-with-prefix': {
        prefix,
      },
    },
    allowContainerCreate: process.env.AZURE_STORAGE_ALLOW_CONTAINER_CREATE === 'true',
    baseURL: process.env.AZURE_STORAGE_ACCOUNT_BASEURL,
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
    containerName: process.env.AZURE_STORAGE_CONTAINER_NAME,
  }),
],
21})

Configuration Options

Option	Description	Default
`enabled`	Whether or not to enable the plugin	`true`
`collections`	Collections to apply the Azure Blob adapter to
`allowContainerCreate`	Whether or not to allow the container to be created if it does not exist	`false`
`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

Installation

1pnpm add @payloadcms/storage-gcs

Usage

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.

1import { gcsStorage } from '@payloadcms/storage-gcs'
2import { Media } from './collections/Media'
3import { MediaWithPrefix } from './collections/MediaWithPrefix'
4
5export default buildConfig({
collections: [Media, MediaWithPrefix],
plugins: [
  gcsStorage({
    collections: {
      media: true,
      'media-with-prefix': {
        prefix,
      },
    },
    bucket: process.env.GCS_BUCKET,
    options: {
      apiEndpoint: process.env.GCS_ENDPOINT,
      projectId: process.env.GCS_PROJECT_ID,
    },
  }),
],
22})

Configuration Options

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
`acl`	Access control list for files that are uploaded	`Private`
`clientUploads`	Do uploads directly on the client to bypass limits on Vercel.

Uploadthing Storage

@payloadcms/storage-uploadthing

Installation

1pnpm add @payloadcms/storage-uploadthing

Usage

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.

1export default buildConfig({
collections: [Media],
plugins: [
  uploadthingStorage({
    collections: {
      media: true,
    },
    options: {
      token: process.env.UPLOADTHING_TOKEN,
      acl: 'public-read',
    },
  }),
],
14})

Configuration Options

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

If you need to create a custom storage adapter, you can use the @payloadcms/plugin-cloud-storage package. This package is used internally by the storage adapters mentioned above.

Installation

pnpm add @payloadcms/plugin-cloud-storage

Usage

Reference any of the existing storage adapters for guidance on how this should be structured. Create an adapter following the GeneratedAdapter interface. Then, pass the adapter to the cloudStorage plugin.

1export interface GeneratedAdapter {
/**
 * Additional fields to be injected into the base collection and image sizes
 */
fields?: Field[]
/**
 * Generates the public URL for a file
 */
generateURL?: GenerateURL
handleDelete: HandleDelete
handleUpload: HandleUpload
name: string
onInit?: () => void
staticHandler: StaticHandler
15}

1import { buildConfig } from 'payload'
2import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'
3
4export default buildConfig({
5  plugins: [
6    cloudStorage({
7      collections: {
8        'my-collection-slug': {
9          adapter: theAdapterToUse, // see docs for the adapter you want to use
10        },
11      },
12    }),
13  ],
14  // The rest of your config goes here
15})

Plugin options

This plugin is configurable to work across many different Payload collections. A * denotes that the property is required.

Option	Type	Description
`collections` *	`Record<string, CollectionOptions>`	Object with keys set to the slug of collections you want to enable the plugin for, and values set to collection-specific options.
`enabled`	`boolean`	To conditionally enable/disable plugin. Default: `true`.

Collection-specific options

Option	Type	Description
`adapter` *	Adapter	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
`prefix`	`string`	Set to `media/images` to upload files inside `media/images` folder in the bucket.
`generateFileURL`	GenerateFileURL	Override the generated file URL with one that you create.

Payload Access Control

Payload ships with Access Control that runs even on statically served files. The same read Access Control property on your upload-enabled collections is used, and it allows you to restrict who can request your uploaded files.

To preserve this feature, by default, this plugin keeps all file URLs exactly the same. Your file URLs won't be updated to point directly to your cloud storage source, as in that case, Payload's Access control will be completely bypassed and you would need public readability on your cloud-hosted files.

Instead, all uploads will still be reached from the default /collectionSlug/staticURL/filename path. This plugin will "pass through" all files that are hosted on your third-party cloud service—with the added benefit of keeping your existing Access Control in place.

If this does not apply to you (your upload collection has read: () => true or similar) you can disable this functionality by setting disablePayloadAccessControl to true. When this setting is in place, this plugin will update your file URLs to point directly to your cloud host.

Conditionally Enabling/Disabling

The proper way to conditionally enable/disable this plugin is to use the enabled property.

1cloudStoragePlugin({
enabled: process.env.MY_CONDITION === 'true',
collections: {
  'my-collection-slug': {
    adapter: theAdapterToUse, // see docs for the adapter you want to use
  },
},
8}),

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Storage Adapters

Vercel Blob Storage

Installation

Usage

Configuration Options

S3 Storage

Installation

Usage

Configuration Options

Azure Blob Storage

Installation

Usage

Configuration Options

Google Cloud Storage

Installation

Usage

Configuration Options

Uploadthing Storage

Installation

Usage

Configuration Options

Custom Storage Adapters

Installation

Usage

Plugin options

Collection-specific options

Payload Access Control

Conditionally Enabling/Disabling

Email Functionality