Skip to content
XenonDocs
Esc
    GitHub
    Docs

    S3-compatible storage

    Store media uploads and binary attachments in Amazon S3, Cloudflare R2, or compatible object stores.

    On this page

    S3 adapter configuration

    You can store uploaded media assets in any S3-compatible object store using the S3 storage adapter.

    src/xenon.config.ts
    import { defineConfig } from "xenon-cms";
    import { S3StorageAdapter } from "xenon-cms/storage/s3";
    
    export default defineConfig({
      collections: [],
      storage: new S3StorageAdapter({
        bucket: process.env.S3_BUCKET!,
        endpoint: process.env.S3_ENDPOINT!,
        region: process.env.S3_REGION ?? "auto",
        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
        publicUrl: process.env.S3_PUBLIC_URL!,
        prefix: "uploads",
      }),
    });

    The adapter uses aws4fetch to authenticate requests and supports Amazon S3, Cloudflare R2, MinIO, and Backblaze B2.

    Adapter options

    OptionTypeDefaultDescription
    bucketstringRequiredTarget bucket name.
    endpointstringRequiredAPI endpoint URL (e.g., https://<account>.r2.cloudflarestorage.com).
    regionstring"auto"AWS region or "auto" for Cloudflare R2.
    accessKeyIdstringRequiredS3 access key ID.
    secretAccessKeystringRequiredS3 secret access key.
    publicUrlstringRequiredBase URL where uploaded files can be retrieved via HTTP.
    prefixstringundefinedOptional subfolder prefix prepended to all storage keys and public URLs.

    Cloudflare R2 example

    Cloudflare R2 provides S3-compatible storage without egress bandwidth charges:

    TypeScript
    storage: new S3StorageAdapter({
      bucket: "my-xenon-media",
      endpoint: `https://${process.env.CF_ACCOUNT_ID}.r2.cloudflarestorage.com`,
      region: "auto",
      accessKeyId: process.env.CF_R2_ACCESS_KEY_ID!,
      secretAccessKey: process.env.CF_R2_SECRET_ACCESS_KEY!,
      publicUrl: "https://media.example.com",
    }),

    Files are uploaded to {bucket}/{prefix}/{collection}/{year}/{month}/{file} and served directly from {publicUrl}/{prefix}/....

    Next steps