Installation

npm i payload-plugin-cloud-storage

yarn add payload-plugin-cloud-storage

Basic Usage

1. Instantiate an adapter

Adapters encapsulate all vendor-specific configuration and API calls.

Currently we only support S3 or S3-compatible APIs (like DigitalOcean spaces) but this will change soon!

import { S3Adapter } from 'payload-plugin-cloud-storage';

const s3Adapter = new S3Adapter(
  {
    endpoint: `https://${process.env.SPACES_REGION}.digitaloceanspaces.com`,
    region: process.env.SPACES_REGION,
    credentials: {
      accessKeyId: process.env.SPACES_KEY,
      secretAccessKey: process.env.SPACES_SECRET,
    },
  },
  {
    bucket: process.env.SPACES_NAME,
    endpointUrl: `https://${process.env.SPACES_NAME}.${process.env.SPACES_REGION}.cdn.digitaloceanspaces.com`
  },
  // optional, use your own getEndpoint method
  (endpointUrl, file) => {
    return `${endpoint}/${data.filename}`
  }
)

2. Add the plugin to Payloads configuration

The plugin attaches itself to all collections that specify an upload key. The at it's most basic, the plugin will provide:

• A beforeChange hook that pushes uploaded files to the relevant cloud storage.
• An afterDelete hook that removes files from cloud storage after the document has been deleted in Payload.
• An afterRead hook that adds returns an endpoint to the file for both the main file and each of the sizes.
• A custom upload.adminThumbnail function. See admin thumbnails for a detailed explanation on what this function does.

const config = buildConfig({
  serverURL: 'http://localhost:3000',
  collections: [
    {
      slug: 'images',
      upload: true, // uploads being enabled is what enables this plugin on the collection
      fields: []
    }
  ],
  plugins: [
    cloudStorage(s3Adapter)
  ]
})

Referencing files uploaded by the plugin

By default the endpoint property is named cloudStorageUrl and it is added to both the main document and each of the image sizes on the collections afterRead hook.

{
  "id": "6110b3ba2ecab80501b31fa6",
  "width": 1247,
  "height": 968,
  "sizes": {
    "mobile": {
      "width": 1000,
      "height": 1000,
      "filename": "test-5-1000x1000.jpg",
      "mimeType": "image/jpeg",
      "filesize": 41329,
      "cloudStorageUrl": "https://brightvision.fra1.cdn.digitaloceanspaces.com/test-1000x1000.jpg"
    }
  },
  "filename": "test.jpg",
  "filesize": 142083,
  "mimeType": "image/jpeg",
  "createdAt": "2021-08-09T04:48:58.577Z",
  "updatedAt": "2021-08-09T04:57:16.992Z",
  "cloudStorageUrl": "https://brightvision.fra1.cdn.digitaloceanspaces.com/test.jpg"
}

Admin Thumbnails

The admin thumbnail function the plugin provides tries to transparently support the same functions that Payload itself does.

If your collection has an upload.adminThumbnail set as string, then it will try to pull the image from that size same as the default behavior. If somehow that size doesn't exist then it'll fallback to the main image.

If however your collection specifies a GetAdminThumbnail function then that will take precedence over the plugin provided function.

Extra Options

cloudStorage allows you to pass a second options parameter.

| Property | Required | Values | Description | |-------------------------|----------|----------------------------|-------------------------------------------------------------------------------------| | disableEndpointProperty | no | boolean | Disable the afterRead hook and the custom adminThumbnail function entirely. | | endpointPropertyName | no | string | Customize the name of the property that gets added in the plugins afterRead hook. | | disableLocalStorage | no | boolean | Passed through to uploads.disableLocalStorage. Defaults to true. |