diff --git a/packages/plugin-cloud-storage/README.md b/packages/plugin-cloud-storage/README.md index 839bbe27a..5fed5ce18 100644 --- a/packages/plugin-cloud-storage/README.md +++ b/packages/plugin-cloud-storage/README.md @@ -2,13 +2,20 @@ This repository contains the officially supported Payload Cloud Storage plugin. It extends Payload to allow you to store all uploaded media in third-party permanent storage. -#### Requirements +**NOTE:** If you are using Payload 3.0 and one of the following storage services, you can use the following packages instead of this one: -- Payload version `1.0.19` or higher is required +| Service | Package | +| -------------------- | ----------------------------------------------------------------------------------------------------------------- | +| Vercel Blob | [`@payloadcms/storage-vercel-blob`](https://github.com/payloadcms/payload/tree/beta/packages/storage-vercel-blob) | +| AWS S3 | [`@payloadcms/storage-s3`](https://github.com/payloadcms/payload/tree/beta/packages/storage-s3) | +| Azure | [`@payloadcms/storage-azure`](https://github.com/payloadcms/payload/tree/beta/packages/storage-azure) | +| Google Cloud Storage | [`@payloadcms/storage-gcs`](https://github.com/payloadcms/payload/tree/beta/packages/storage-gcs) | + +This package is now best used for implementing custom storage solutions or third-party storage services that do not have `@payloadcms/storage-*` packages. ## Installation -`yarn add @payloadcms/plugin-cloud-storage` or `npm install @payloadcms/plugin-cloud-storage` +`pnpm add @payloadcms/plugin-cloud-storage` ## Usage diff --git a/packages/storage-azure/README.md b/packages/storage-azure/README.md index 081cfd4c2..111012dd5 100644 --- a/packages/storage-azure/README.md +++ b/packages/storage-azure/README.md @@ -1 +1,52 @@ -# Azure Storage +# Azure Blob Storage for Payload + +This package provides a simple way to use [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs) with Payload. + +**NOTE:** This package removes the need to use `@payloadcms/plugin-cloud-storage` as was needed in Payload 2.x. + +## Installation + +```sh +pnpm add @payloadcms/storage-s3 +``` + +## 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. +- 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. + +```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: { + [mediaSlug]: true, + [mediaWithPrefixSlug]: { + 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 + +| 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 | | diff --git a/packages/storage-azure/src/index.ts b/packages/storage-azure/src/index.ts index 3069d60c2..be8092527 100644 --- a/packages/storage-azure/src/index.ts +++ b/packages/storage-azure/src/index.ts @@ -16,8 +16,18 @@ import { getHandleUpload } from './handleUpload.js' import { getHandler } from './staticHandler.js' export type AzureStorageOptions = { + /** + * Whether or not to allow the container to be created if it does not exist + * + * @default false + */ allowContainerCreate: boolean + + /** + * Base URL for the Azure Blob storage account + */ baseURL: string + /** * Collection options to apply the Azure Blob adapter to. */ diff --git a/packages/storage-gcs/README.md b/packages/storage-gcs/README.md index 1740cad35..d053e586e 100644 --- a/packages/storage-gcs/README.md +++ b/packages/storage-gcs/README.md @@ -1 +1,52 @@ -# Nodemailer Email Adapter +# Google Cloud Storage for Payload + +This package provides a simple way to use [Google Cloud Storage](https://cloud.google.com/storage) with Payload. + +**NOTE:** This package removes the need to use `@payloadcms/plugin-cloud-storage` as was needed in Payload 2.x. + +## Installation + +```sh +pnpm add @payloadcms/storage-gcs +``` + +## 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. +- 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. + +```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: { + [mediaSlug]: true, + [mediaWithPrefixSlug]: { + prefix, + }, + }, + bucket: process.env.GCS_BUCKET, + options: { + apiEndpoint: process.env.GCS_ENDPOINT, + projectId: process.env.GCS_PROJECT_ID, + }, + }), + ], +}) +``` + +### 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](https://github.com/googleapis/nodejs-storage) | | +| `acl` | Access control list for files that are uploaded | `Private` | diff --git a/packages/storage-s3/README.md b/packages/storage-s3/README.md index 1740cad35..881ecc4dd 100644 --- a/packages/storage-s3/README.md +++ b/packages/storage-s3/README.md @@ -1 +1,50 @@ -# Nodemailer Email Adapter +# S3 Storage for Payload + +This package provides a simple way to use S3 with Payload. + +**NOTE:** This package removes the need to use `@payloadcms/plugin-cloud-storage` as was needed in Payload 2.x. + +## Installation + +```sh +pnpm add @payloadcms/storage-s3 +``` + +## 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. +- 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. + +```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: { + [mediaSlug]: true, + [mediaWithPrefixSlug]: { + 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 + +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. diff --git a/packages/storage-vercel-blob/README.md b/packages/storage-vercel-blob/README.md index 8c7948fed..a4472dca1 100644 --- a/packages/storage-vercel-blob/README.md +++ b/packages/storage-vercel-blob/README.md @@ -1 +1,49 @@ -# Vercel Blob Storage +# Vercel Blob Storage for Payload + +This package provides a simple way to use [Vercel Blob](https://vercel.com/docs/storage/vercel-blob) storage with Payload. + +**NOTE:** This package removes the need to use `@payloadcms/plugin-cloud-storage` as was needed in Payload 2.x. + +## Installation + +```sh +pnpm 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. + +```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.slug]: true, + [MediaWithPrefix.slug]: { + prefix: 'my-prefix', + }, + }, + // Token provided by Vercel once Blob storage is added to your Vercel project + token: process.env.BLOB_READ_WRITE_TOKEN, + }), + ], +}) +``` + +| 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 | `''` | diff --git a/packages/storage-vercel-blob/src/index.ts b/packages/storage-vercel-blob/src/index.ts index f8392be23..f79ad9296 100644 --- a/packages/storage-vercel-blob/src/index.ts +++ b/packages/storage-vercel-blob/src/index.ts @@ -14,14 +14,15 @@ import { getStaticHandler } from './staticHandler.js' export type VercelBlobStorageOptions = { /** - * Access control level + * Access control level. Currently, only 'public' is supported. + * Vercel plans on adding support for private blobs in the future. * * @default 'public' */ access?: 'public' /** - * Add a random suffix to the uploaded file name + * Add a random suffix to the uploaded file name in Vercel Blob storage * * @default false */ @@ -30,7 +31,7 @@ export type VercelBlobStorageOptions = { /** * Cache-Control max-age in seconds * - * @default 31536000 (1 year) + * @defaultvalue 365 * 24 * 60 * 60 (1 Year) */ cacheControlMaxAge?: number