Supabase streamlines the process of working with file storage by offering an S3-compatible API. This compatibility enables developers to integrate Supabase Storage seamlessly with any library or tool that supports the S3 protocol, such as those designed for Amazon S3. Leveraging this feature allows you to implement robust file management without having to learn a proprietary system, making Supabase a practical and efficient choice for both new and existing applications.

About Payload CMS and S3 Integration

Payload CMS is a flexible, headless content management system tailored for building custom digital experiences. It provides full control over backend functionality and integrates smoothly with modern development workflows. One of its powerful features is the ability to use an S3 Storage adapter, allowing integration with any S3-compatible provider, including Supabase.

To begin using Supabase Storage with Payload CMS, refer to the Payload CMS documentation. Here’s how to get started:

Step 1: Install the S3 Storage Adapter

Run the following command to install the official Payload S3 adapter:

pnpm add @payloadcms/storage-s3

Step 2: Configure Your payload.config.ts File

After installation, configure the adapter in your Payload project by updating your payload.config.ts file.

Import Necessary Modules

import { s3Storage } from '@payloadcms/storage-s3'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

Export Payload Configuration

Initialize the S3 storage plugin as part of the Payload configuration:

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,
        endpoint: process.env.S3_ENDPOINT,
        forcePathStyle: true,
      },
    }),
  ],
})

Step 3: Set Environment Variables

To ensure compatibility with Supabase’s S3 API, you must set both the endpoint and forcePathStyle properties. These ensure that Payload CMS can interface properly with Supabase’s object storage system.

In your .env file, define the following variables using values found in your Supabase Dashboard under the S3 Connection section:

S3_ENDPOINT=https://your-supabase-project.supabase.co/storage/v1/s3
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET=your-bucket-name
S3_REGION=your-region

Bonus step for local development with Supabase CLI

For users of the CLI in local development your .env file would contain these default credentials instead of the above:

S3_ENDPOINT=http://127.0.0.1:54321/storage/v1/s3
S3_ACCESS_KEY_ID=625729a08b95bf1b7ff351a663f3a23c
S3_SECRET_ACCESS_KEY=850181e4652dd023b7a98c58ae0d2d34bd487ee0cc3254aed6eda37307425907
S3_BUCKET=your-bucket-name
S3_REGION=local

These credentials allow Payload to authenticate and perform operations against your Supabase Storage instance.

Additional Resources

For more information on Supabase security and authorization practices, review the S3 Authentication Guide. This resource covers topics such as access control, token handling, and secure communication when working with S3-compatible APIs.

By combining Payload CMS’s adaptability with Supabase’s S3-compatible API, you can build scalable, customizable file storage solutions with minimal overhead and maximum flexibility.