800c424777
Adds pre-signed URLs support file downloads with the S3 adapter. Can be
enabled per-collection:
```ts
s3Storage({
collections: {
media: { signedDownloads: true }, // or { signedDownloads: { expiresIn: 3600 }} for custom expiresIn (default 7200)
},
bucket: process.env.S3_BUCKET,
config: {
credentials: {
accessKeyId: process.env.S3_ACCESS_KEY_ID,
secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
},
endpoint: process.env.S3_ENDPOINT,
forcePathStyle: process.env.S3_FORCE_PATH_STYLE === 'true',
region: process.env.S3_REGION,
},
}),
```
The main use case is when you care about the Payload access control (so
you don't want to use `disablePayloadAccessControl: true` but you don't
want your files to be served through Payload (which can affect
performance with large videos for example).
This feature instead generates a signed URL (after verifying the access
control) and redirects you directly to the S3 provider.
This is an addition to https://github.com/payloadcms/payload/pull/11382
which added pre-signed URLs for file uploads.
363 lines
19 KiB
Plaintext
363 lines
19 KiB
Plaintext
---
|
|
title: Storage Adapters
|
|
label: Storage Adapters
|
|
order: 20
|
|
desc: Payload provides 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, Uploadthing, and more.
|
|
keywords: uploads, images, media, storage, adapters, s3, vercel, google cloud, azure
|
|
---
|
|
|
|
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`](https://github.com/payloadcms/payload/tree/main/packages/storage-vercel-blob) |
|
|
| AWS S3 | [`@payloadcms/storage-s3`](https://github.com/payloadcms/payload/tree/main/packages/storage-s3) |
|
|
| Azure | [`@payloadcms/storage-azure`](https://github.com/payloadcms/payload/tree/main/packages/storage-azure) |
|
|
| Google Cloud Storage | [`@payloadcms/storage-gcs`](https://github.com/payloadcms/payload/tree/main/packages/storage-gcs) |
|
|
| Uploadthing | [`@payloadcms/storage-uploadthing`](https://github.com/payloadcms/payload/tree/main/packages/storage-uploadthing) |
|
|
|
|
## Vercel Blob Storage
|
|
|
|
[`@payloadcms/storage-vercel-blob`](https://www.npmjs.com/package/@payloadcms/storage-vercel-blob)
|
|
|
|
### Installation#vercel-blob-installation
|
|
|
|
```sh
|
|
pnpm add @payloadcms/storage-vercel-blob
|
|
```
|
|
|
|
### Usage#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.
|
|
|
|
```ts
|
|
import { vercelBlobStorage } from '@payloadcms/storage-vercel-blob'
|
|
import { Media } from './collections/Media'
|
|
import { MediaWithPrefix } from './collections/MediaWithPrefix'
|
|
|
|
export 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,
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
### Configuration Options#vercel-blob-configuration
|
|
|
|
| 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`](https://www.npmjs.com/package/@payloadcms/storage-s3)
|
|
|
|
### Installation#s3-installation
|
|
|
|
```sh
|
|
pnpm add @payloadcms/storage-s3
|
|
```
|
|
|
|
### Usage#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`](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.
|
|
- Configure `signedDownloads` (either globally of per-collection in `collections`) to use [presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) for files downloading. This can improve performance for large files (like videos) while still respecting your access control.
|
|
|
|
```ts
|
|
import { s3Storage } from '@payloadcms/storage-s3'
|
|
import { Media } from './collections/Media'
|
|
import { MediaWithPrefix } from './collections/MediaWithPrefix'
|
|
|
|
export 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
|
|
},
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
### Configuration Options#s3-configuration
|
|
|
|
See the the [AWS SDK Package](https://github.com/aws/aws-sdk-js-v3) and [`S3ClientConfig`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3) object for guidance on AWS S3 configuration.
|
|
|
|
## Azure Blob Storage
|
|
|
|
[`@payloadcms/storage-azure`](https://www.npmjs.com/package/@payloadcms/storage-azure)
|
|
|
|
### Installation#azure-installation
|
|
|
|
```sh
|
|
pnpm add @payloadcms/storage-azure
|
|
```
|
|
|
|
### Usage#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.
|
|
|
|
```ts
|
|
import { azureStorage } from '@payloadcms/storage-azure'
|
|
import { Media } from './collections/Media'
|
|
import { MediaWithPrefix } from './collections/MediaWithPrefix'
|
|
|
|
export 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,
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
### Configuration Options#azure-configuration
|
|
|
|
| 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`](https://www.npmjs.com/package/@payloadcms/storage-gcs)
|
|
|
|
### Installation#gcs-installation
|
|
|
|
```sh
|
|
pnpm add @payloadcms/storage-gcs
|
|
```
|
|
|
|
### Usage#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.
|
|
|
|
```ts
|
|
import { gcsStorage } from '@payloadcms/storage-gcs'
|
|
import { Media } from './collections/Media'
|
|
import { MediaWithPrefix } from './collections/MediaWithPrefix'
|
|
|
|
export 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,
|
|
},
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
### 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` |
|
|
| `clientUploads` | Do uploads directly on the client to bypass limits on Vercel. | |
|
|
|
|
## Uploadthing Storage
|
|
|
|
[`@payloadcms/storage-uploadthing`](https://www.npmjs.com/package/@payloadcms/storage-uploadthing)
|
|
|
|
### Installation#uploadthing-installation
|
|
|
|
```sh
|
|
pnpm add @payloadcms/storage-uploadthing
|
|
```
|
|
|
|
### Usage#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.
|
|
|
|
```ts
|
|
export default buildConfig({
|
|
collections: [Media],
|
|
plugins: [
|
|
uploadthingStorage({
|
|
collections: {
|
|
media: true,
|
|
},
|
|
options: {
|
|
token: process.env.UPLOADTHING_TOKEN,
|
|
acl: 'public-read',
|
|
},
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
### 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` |
|
|
| `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`](https://www.npmjs.com/package/@payloadcms/plugin-cloud-storage) package. This package is used internally by the storage adapters mentioned above.
|
|
|
|
### Installation#custom-installation
|
|
|
|
`pnpm add @payloadcms/plugin-cloud-storage`
|
|
|
|
### Usage#custom-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.
|
|
|
|
```ts
|
|
export 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
|
|
}
|
|
```
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'
|
|
|
|
export default buildConfig({
|
|
plugins: [
|
|
cloudStorage({
|
|
collections: {
|
|
'my-collection-slug': {
|
|
adapter: theAdapterToUse, // see docs for the adapter you want to use
|
|
},
|
|
},
|
|
}),
|
|
],
|
|
// The rest of your config goes here
|
|
})
|
|
```
|
|
|
|
## 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](https://github.com/payloadcms/payload/blob/main/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) |
|
|
| `prefix` | `string` | Set to `media/images` to upload files inside `media/images` folder in the bucket. |
|
|
| `generateFileURL` | [GenerateFileURL](https://github.com/payloadcms/payload/blob/main/packages/plugin-cloud-storage/src/types.ts#L67) | Override the generated file URL with one that you create. |
|
|
|
|
## Payload Access Control
|
|
|
|
Payload ships with [Access Control](../access-control/overview) 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.
|
|
|
|
```ts
|
|
cloudStoragePlugin({
|
|
enabled: process.env.MY_CONDITION === 'true',
|
|
collections: {
|
|
'my-collection-slug': {
|
|
adapter: theAdapterToUse, // see docs for the adapter you want to use
|
|
},
|
|
},
|
|
}),
|
|
```
|