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 |
@payloadcms/storage-vercel-blob
collections
object to specify which collections should use the Vercel Blob adapter. The slug must match one of your existing collection slugs.BLOB_READ_WRITE_TOKEN
set in your Vercel environment variables. This is usually set by Vercel automatically after adding blob storage to your project.disableLocalStorage
to true
for each collection.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 | '' |
collections
object to specify which collections should use the Vercel Blob adapter. The slug must match one of your existing collection slugs.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.disableLocalStorage
to true
for each collection.See the the AWS SDK Package and S3ClientConfig
object for guidance on AWS S3 configuration.
collections
object to specify which collections should use the Vercel Blob adapter. The slug must match one of your existing collection slugs.disableLocalStorage
to true
for each collection.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 |
collections
object to specify which collections should use the Vercel Blob adapter. The slug must match one of your existing collection slugs.disableLocalStorage
to true
for each collection.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 |
@payloadcms/storage-uploadthing
collections
object to specify which collections should use uploadthing. The slug must match one of your existing collection slugs and be an upload
type.apiKey
in the options
object.acl
is optional and defaults to public-read
.Option | Description | Default |
---|---|---|
apiKey | API key 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 |
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.
pnpm add @payloadcms/plugin-cloud-storage
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.
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. |
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 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.
The proper way to conditionally enable/disable this plugin is to use the enabled
property.