Storage Adapters

FrogBot 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	`@frogbotai/storage-vercel-blob`
AWS S3	`@frogbotai/storage-s3`
Azure	`@frogbotai/storage-azure`
Google Cloud Storage	`@frogbotai/storage-gcs`
R2	`@frogbotai/storage-r2`

Configuration

Add a storage adapter to the root storage key. Without further configuration, it stores the files for FrogBot’s own upload collections:

The files collection: the collection marked file: true, if any.
frogbot-chat-assets, when chat persistence is enabled.

import { s3Storage } from '@frogbotai/storage-s3'
import { buildConfig } from 'frogbot'

export default buildConfig({
  storage: [
    s3Storage({
      bucket: process.env.S3_BUCKET,
      config: { region: process.env.S3_REGION },
    }),
  ],
  // ... rest of config
})

List your own upload collections in collections. To keep one of FrogBot’s collections on local disk, set it to false:

s3Storage({
  bucket: process.env.S3_BUCKET,
  config: { region: process.env.S3_REGION },
  collections: {
    media: true,
    'frogbot-chat-assets': false,
  },
})

Storage adapters run after every plugin, so an adapter also covers collections that plugins add.

Multiple adapters

FrogBot’s collections go to the first storage adapter in storage. To store one of them with a different adapter, list it in that adapter’s collections. Setting one to false only takes effect in the first adapter. Listing the same collection in two adapters stops FrogBot at startup with an error.

import { s3Storage } from '@frogbotai/storage-s3'
import { vercelBlobStorage } from '@frogbotai/storage-vercel-blob'
import { buildConfig } from 'frogbot'

export default buildConfig({
  storage: [
    s3Storage({
      bucket: process.env.S3_BUCKET,
      config: { region: process.env.S3_REGION },
    }),
    vercelBlobStorage({
      collections: { files: true },
      token: process.env.BLOB_READ_WRITE_TOKEN,
    }),
  ],
  // ... rest of config
})

This app declares a files collection marked file: true. Here files uses Vercel Blob and frogbot-chat-assets uses S3.

Vercel Blob Storage

@frogbotai/storage-vercel-blob

Installation#vercel-blob-installation

pnpm add @frogbotai/storage-vercel-blob

Usage#vercel-blob-usage

FrogBot’s upload collections use the adapter automatically. Add your own upload collections to collections; each slug must match an existing upload collection.
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.

import { vercelBlobStorage } from '@frogbotai/storage-vercel-blob'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  storage: [
    vercelBlobStorage({
      enabled: true, // Optional, defaults to true
      // Your own upload collections; FrogBot's are included automatically
      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

Also accepts the shared options.

Option	Type	Default	Description
`token`	`string \| undefined`	Required	Vercel Blob read/write token, in the form `vercel_blob_rw_<store_id>_<random>`. Another format throws at startup. When the token is empty or `undefined`, the adapter is disabled.
`access`	`'public'`	`'public'`	Blob access level. Vercel Blob supports only public blobs.
`addRandomSuffix`	`boolean`	`false`	Adds a random suffix to uploaded file names in Vercel Blob.
`cacheControlMaxAge`	`number`	`31536000` (one year)	`Cache-Control` max-age for uploaded files, in seconds.

S3 Storage

@frogbotai/storage-s3

Installation#s3-installation

pnpm add @frogbotai/storage-s3

Usage#s3-usage

FrogBot’s upload collections use the adapter automatically. Add your own upload collections to collections; each slug must match an existing upload collection.
The config object can be any S3ClientConfig object (from @aws-sdk/client-s3). 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 or per-collection in collections) to use presigned URLs for files downloading. This can improve performance for large files (like videos) while still respecting your access control. Additionally, with signedDownloads.shouldUseSignedURL you can specify a condition whether FrogBot should use a presigned URL, if you want to use this feature only for specific files.
You can conditionally enable the adapter using the enabled option. For example, enabled: Boolean(process.env.S3_BUCKET) skips the adapter in local development when credentials are not set.

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

export default buildConfig({
  collections: [Media, MediaWithPrefix, Videos],
  storage: [
    s3Storage({
      collections: {
        media: true,
        'media-with-prefix': {
          prefix,
        },
        videos: {
          // Filter only mp4 files
          signedDownloads: {
            shouldUseSignedURL: ({ collection, filename, req }) => {
              return filename.endsWith('.mp4')
            },
          },
        },
      },
      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

Also accepts the shared options. Entries in collections also accept signedDownloads, which overrides the adapter-level setting for that collection.

Option	Type	Default	Description
`bucket`	`string`	Required	Name of the S3 bucket.
`config`	`S3ClientConfig`	Required	Options for the AWS SDK S3 client. Merged over a default request handler that keeps connections alive, with up to 100 sockets.
`acl`	`'private' \| 'public-read'`	—	Access control list applied to uploaded files and client-upload URLs. Unset uses the bucket’s default.
`signedDownloads`	`boolean \| SignedDownloadsConfig`	`false`	Redirects file requests to presigned URLs after access control runs. See Signed downloads.
`clientCacheKey`	`string`	`s3:<bucket>`	Key the S3 client is cached under. Adapters with the same key share one client.
`disableLocalStorage`	`boolean`	—	Accepted but not read. Local storage is always disabled for the collections the adapter covers; set `disableLocalStorage` on a collection entry instead.

Signed downloads

Option	Type	Default	Description
`expiresIn`	`number`	`900`	Seconds the presigned URL stays valid. `signedDownloads: true` uses `7200`.
`shouldUseSignedURL`	`({ collection, filename, req }) => boolean \| Promise<boolean>`	Always	Return `false` to serve a file through FrogBot instead of redirecting to a presigned URL.

For full S3ClientConfig options, see the AWS SDK Package and S3ClientConfig docs.

Using with Cloudflare R2 (via S3 API)#s3-r2

Cloudflare R2 exposes an S3-compatible API, so you can use @frogbotai/storage-s3 to connect to it. This is the recommended approach when deploying to Vercel, Netlify, or any Node.js environment. (The @frogbotai/storage-r2 adapter is for Cloudflare Workers only, where R2 is available as a native bucket binding.)

import { s3Storage } from '@frogbotai/storage-s3'

export default buildConfig({
  collections: [Media],
  storage: [
    s3Storage({
      enabled: Boolean(process.env.R2_BUCKET),
      collections: {
        media: {
          disablePayloadAccessControl: true,
          generateFileURL: ({ filename, prefix }) => {
            const key = prefix ? `${prefix}/${filename}` : filename
            return `${process.env.R2_PUBLIC_URL}/${key}`
          },
        },
      },
      bucket: process.env.R2_BUCKET,
      config: {
        credentials: {
          accessKeyId: process.env.R2_ACCESS_KEY_ID,
          secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
        },
        region: 'auto',
        // R2 S3 API endpoint — for uploads only, not for serving files
        endpoint: process.env.R2_ENDPOINT,
        forcePathStyle: true,
      },
    }),
  ],
})

Required environment variables:

R2_BUCKET=my-bucket
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_ENDPOINT=https://<accountId>.r2.cloudflarestorage.com
R2_PUBLIC_URL=https://media.yourdomain.com

region: 'auto' — required by R2; standard AWS region values are not accepted
endpoint — your R2 S3 API endpoint from the Cloudflare dashboard. This is for uploads only — not for serving files
forcePathStyle: true — required for R2’s path-style bucket addressing
R2_PUBLIC_URL — your bucket’s public URL (either the *.r2.dev subdomain or a custom domain you’ve connected in Cloudflare). This is separate from the S3 API endpoint
disablePayloadAccessControl: true — bypasses FrogBot’s file proxy so URLs point directly to your public R2 domain

Azure Blob Storage

@frogbotai/storage-azure

Installation#azure-installation

pnpm add @frogbotai/storage-azure

Usage#azure-usage

FrogBot’s upload collections use the adapter automatically. Add your own upload collections to collections; each slug must match an existing upload collection.
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.

import { azureStorage } from '@frogbotai/storage-azure'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  storage: [
    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

Also accepts the shared options.

Option	Type	Default	Description
`connectionString`	`string`	Required	Azure Blob storage connection string.
`containerName`	`string`	Required	Name of the blob container.
`baseURL`	`string`	Required	Base URL of the storage account. File URLs are built as `<baseURL>/<containerName>/<key>`.
`allowContainerCreate`	`boolean`	Required	Creates the container on startup if it doesn’t exist.
`containerAccess`	`'private' \| 'blob' \| 'container'`	`'private'`	Public access level for a container the adapter creates. Applies only with `allowContainerCreate`.
`clientUploads`	`boolean \| { access?: ClientUploadsAccess; chunkLargeFiles?: boolean }`	`false`	Client uploads, as in the shared options. `chunkLargeFiles` uploads in blocks to lift the roughly 5 GB single-request limit, and needs CORS that allows `OPTIONS`, `PUT`, and `x-ms-*` headers. Client uploads apply only to collections with `upload.allowRestrictedFileTypes: true`.
`clientCacheKey`	`string`	—	Accepted but not read.

Google Cloud Storage

@frogbotai/storage-gcs

Installation#gcs-installation

pnpm add @frogbotai/storage-gcs

Usage#gcs-usage

FrogBot’s upload collections use the adapter automatically. Add your own upload collections to collections; each slug must match an existing upload collection.
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.

import { gcsStorage } from '@frogbotai/storage-gcs'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  storage: [
    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

Also accepts the shared options.

Option	Type	Default	Description
`bucket`	`string`	Required	Name of the bucket.
`options`	`StorageOptions`	Required	Google Cloud Storage client options, such as `projectId` and credentials.
`acl`	`'Private' \| 'Public'`	—	Makes each uploaded file private or public. Unset leaves the bucket’s default.
`clientCacheKey`	`string`	`gcs:<bucket>`	Key the storage client is cached under. Adapters with the same key share one client.

R2 Storage

@frogbotai/storage-r2 Use this adapter to store uploads in a Cloudflare R2 bucket via the Cloudflare Workers environment. If you’re connecting to R2 from a Node.js environment (Vercel, Netlify, etc.) using the S3-compatible API, see Using with Cloudflare R2 (via S3 API) instead.

Installation#r2-installation

pnpm add @frogbotai/storage-r2

Usage#r2-usage

FrogBot’s upload collections use the adapter automatically. Add your own upload collections to collections; each slug must match an existing upload collection.
Pass in the R2 bucket binding to the bucket option, this should be done in the environment where FrogBot is running (e.g. Cloudflare Worker).
You can conditionally enable the adapter with the enabled option.

export default buildConfig({
  collections: [Media],
  storage: [
    r2Storage({
      collections: {
        media: true,
      },
      bucket: cloudflare.env.R2,
    }),
  ],
})

Configuration Options#r2-configuration

Also accepts the shared options.

Option	Type	Default	Description
`bucket`	`R2Bucket`	Required	The R2 bucket binding from your Cloudflare Worker environment.
`copyCredentials`	`{ accessKeyId, accountId, bucket, secretAccessKey }`	—	S3 API credentials for the bucket. Only needed for file versioning operations that copy objects.

Shared storage options

Every storage adapter accepts these options, except where noted.

Option	Type	Default	Description
`collections`	`Record<string, true \| false \| CollectionOptions>`	`{}`	Your own upload collections that use the adapter, keyed by slug. The collection marked `file: true`, if any, and `frogbot-chat-assets` are included automatically in the first adapter. Use `true` for the defaults, an object of collection-specific options, or `false` to keep one of FrogBot’s collections on local disk. Each slug must match an existing upload collection.
`enabled`	`boolean`	`true`	Set `false` to turn the adapter off. When it’s off, the collections keep using local storage.
`clientUploads`	`boolean \| { access?: ClientUploadsAccess }`	`false`	Uploads files directly from the browser to storage, bypassing server upload limits such as Vercel’s 4.5 MB. The user must be signed in and able to create or update documents in the collection. `access` is `({ collectionSlug, req }) => boolean \| Promise<boolean>` and adds a further check. Azure accepts extra keys.
`useCompositePrefixes`	`boolean`	`false`	Stores the document prefix relative to the collection prefix. See Prefix composition.

Collection-specific options

Option	Type	Default	Description
`prefix`	`string`	—	Folder in the bucket for this collection’s files, such as `media/images`.
`disableLocalStorage`	`boolean`	`true`	Set `false` to also keep a local copy of each file.
`disablePayloadAccessControl`	`true`	—	Serves files straight from your storage provider instead of through FrogBot’s access control. See FrogBot Access Control.
`generateFileURL`	`({ collection, filename, prefix, size }) => string \| Promise<string>`	—	Returns the file URL to store, instead of the generated one. `size` is set for image sizes.
`signedDownloads`	`boolean \| SignedDownloadsConfig`	The adapter’s `signedDownloads`	S3 only. Overrides signed downloads for this collection.

Prefix Composition

Storage adapters support two types of prefixes:

Collection prefix: Set at the adapter configuration level (e.g., prefix: 'media-folder')
Document prefix: Set per-document via the prefix field on the upload collection

New uploads are always stored beneath the collection prefix. useCompositePrefixes changes how a document prefix is read and stored:

Default (false): the document prefix is a full path. If it already starts with the collection prefix, it’s used as-is; otherwise it’s nested beneath the collection prefix, and the stored prefix field holds the combined path.
true: the document prefix is always relative. It’s joined to the collection prefix when the file key is built, and the stored prefix field holds only the document part.

Collection prefix: uploads
Document prefix:   user-123
Default:           uploads/user-123/image.jpg
Composite:         uploads/user-123/image.jpg

Collection prefix: uploads
Document prefix:   uploads/documents
Default:           uploads/documents/image.jpg
Composite:         uploads/uploads/documents/image.jpg

Files uploaded before you change the setting keep the prefix they were stored with, for reads, URLs, and cleanup. This is useful when you want a base folder structure (collection prefix) while still allowing per-document organization (document prefix).

storage: [
  s3Storage({
    collections: {
      media: {
        prefix: 'uploads', // All files go under uploads/
      },
    },
    useCompositePrefixes: true, // Document prefixes append to collection prefix
    bucket: process.env.S3_BUCKET,
    // ...
  }),
],

FrogBot Access Control

FrogBot ships with Access Control 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, storage adapters keep 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, FrogBot’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. Storage adapters 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, the adapter will update your file URLs to point directly to your cloud host. For a concrete example, see Using with Cloudflare R2 (via S3 API).

Conditionally Enabling/Disabling

Use the adapter’s enabled property to conditionally enable or disable cloud storage. When disabled, local uploads remain available unless the collection disables local storage.

import { s3Storage } from '@frogbotai/storage-s3'
import { buildConfig } from 'frogbot'
import { Media } from './collections/Media'

export default buildConfig({
  collections: [Media],
  storage: [
    s3Storage({
      enabled: Boolean(process.env.S3_BUCKET),
      collections: { media: true },
      bucket: process.env.S3_BUCKET ?? '',
      config: { region: process.env.S3_REGION },
    }),
  ],
})

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Configuration

Multiple adapters

Vercel Blob Storage

Installation#vercel-blob-installation

Usage#vercel-blob-usage

Configuration Options#vercel-blob-configuration

S3 Storage

Installation#s3-installation

Usage#s3-usage

Configuration Options#s3-configuration

Signed downloads

Using with Cloudflare R2 (via S3 API)#s3-r2

Azure Blob Storage

Installation#azure-installation

Usage#azure-usage

Configuration Options#azure-configuration

Google Cloud Storage

Installation#gcs-installation

Usage#gcs-usage

Configuration Options#gcs-configuration

R2 Storage

Installation#r2-installation

Usage#r2-usage

Configuration Options#r2-configuration

Shared storage options

Collection-specific options

Prefix Composition

FrogBot Access Control

Conditionally Enabling/Disabling

​Configuration

​Multiple adapters

​Vercel Blob Storage

​Installation#vercel-blob-installation

​Usage#vercel-blob-usage

​Configuration Options#vercel-blob-configuration

​S3 Storage

​Installation#s3-installation

​Usage#s3-usage

​Configuration Options#s3-configuration

​Signed downloads

​Using with Cloudflare R2 (via S3 API)#s3-r2

​Azure Blob Storage

​Installation#azure-installation

​Usage#azure-usage

​Configuration Options#azure-configuration

​Google Cloud Storage

​Installation#gcs-installation

​Usage#gcs-usage

​Configuration Options#gcs-configuration

​R2 Storage

​Installation#r2-installation

​Usage#r2-usage

​Configuration Options#r2-configuration

​Shared storage options

​Collection-specific options

​Prefix Composition

​FrogBot Access Control

​Conditionally Enabling/Disabling

Configuration

Multiple adapters

Vercel Blob Storage

Installation#vercel-blob-installation

Usage#vercel-blob-usage

Configuration Options#vercel-blob-configuration

S3 Storage

Installation#s3-installation

Usage#s3-usage

Configuration Options#s3-configuration

Signed downloads

Using with Cloudflare R2 (via S3 API)#s3-r2

Azure Blob Storage

Installation#azure-installation

Usage#azure-usage

Configuration Options#azure-configuration

Google Cloud Storage

Installation#gcs-installation

Usage#gcs-usage

Configuration Options#gcs-configuration

R2 Storage

Installation#r2-installation

Usage#r2-usage

Configuration Options#r2-configuration

Shared storage options

Collection-specific options

Prefix Composition

FrogBot Access Control

Conditionally Enabling/Disabling