Cloudflare Storage

CloudflareStorage is the Storage component’s Cloudflare R2 backend. It extends the shared Storage base class, which talks to R2 through Bun’s built-in S3 client (R2 is S3-compatible), so you get production object storage with zero egress fees behind the same IStorage interface as every other backend. Switch to or from R2 without changing a single call site.

What R2 brings here

Because R2 speaks S3, the backend runs on Bun’s native S3Client and CloudflareStorage only supplies the connection options. The interface is the same IStorage you use elsewhere: put, getFile, getAsJson, delete, list, and the rest. All transport logic lives in the Storage base class, so the subclass provides only credentials and getOptions(). put() accepts strings, ArrayBuffer, Blob, Request/Response, and BunFile/S3File. The class registers with @decorator.storage() and resolves from the container.

Installation

CloudflareStorage ships with @talosjs/storage. It uses Bun’s built-in S3 client, so there’s no extra SDK to install.

bun add @talosjs/storage

Environment variables

Variable	Required	Purpose
`STORAGE_CLOUDFLARE_ACCESS_KEY`	Yes	R2 access key. Missing throws `StorageException` (`CONFIG_REQUIRED`).
`STORAGE_CLOUDFLARE_SECRET_KEY`	Yes	R2 secret key. Missing throws `StorageException` (`CONFIG_REQUIRED`).
`STORAGE_CLOUDFLARE_ENDPOINT`	Yes	R2 S3 endpoint URL. Missing throws `StorageException` (`CONFIG_REQUIRED`).
`STORAGE_CLOUDFLARE_REGION`	No	R2 region. Defaults to `EEUR`.

STORAGE_CLOUDFLARE_ACCESS_KEY=your_access_key
STORAGE_CLOUDFLARE_SECRET_KEY=your_secret_key
STORAGE_CLOUDFLARE_ENDPOINT=https://your-account.r2.cloudflarestorage.com
STORAGE_CLOUDFLARE_REGION=EEUR

All three required values are validated when CloudflareStorage is constructed, so missing credentials fail fast at startup.

How it works

CloudflareStorage reads its credentials, then getOptions() returns the S3Options the base Storage class uses to build a Bun.S3Client. Calling setBucket() constructs (or rebuilds) the client for that bucket, and from then on every read and write goes through the S3 client. The active bucket is the R2 bucket the client targets.

Method	Purpose
`getBucket()` / `setBucket(name)`	Read or switch the active R2 bucket; `setBucket` chains.
`list()`	List the keys in the current bucket.
`clearBucket()`	Delete every object in the current bucket.
`exists(key)`	Whether an object exists.
`delete(key)`	Remove one object.
`put(key, content)`	Write content; returns the number of bytes written.
`putFile(key, localPath)`	Upload a local file.
`putDir(bucket, options)`	Upload a local directory recursively with an optional `filter` regex.
`getFile(key, options)`	Download an object to `options.outputDir` (optionally renamed).
`getAsJson<T>(key)`	Parse the object as JSON.
`getAsArrayBuffer(key)`	Read the object as an `ArrayBuffer`.
`getAsStream(key)`	Read the object as a `ReadableStream`.

Usage

The API is the same as every other storage backend.

import { container } from "@talosjs/container";
import { CloudflareStorage } from "@talosjs/storage";

const storage = container.get(CloudflareStorage).setBucket("uploads");

// Write content — returns the number of bytes written
await storage.put("avatars/123.png", file); // file: Blob | BunFile | ArrayBuffer | ...
await storage.put("config.json", JSON.stringify({ theme: "dark" }));

// Read it back
const config = await storage.getAsJson<{ theme: string }>("config.json");
const buffer = await storage.getAsArrayBuffer("avatars/123.png");

// Existence, listing, and removal
await storage.exists("avatars/123.png"); // true
const keys = await storage.list();
await storage.delete("avatars/123.png");

Upload a local file or a whole directory, and stream large files instead of buffering them:

// Upload one local file, or a directory recursively (images only)
await storage.putFile("avatars/123.png", "/tmp/avatar.png");
await storage.putDir("avatars", {
  path: "/tmp/avatars",
  filter: /\.(png|jpe?g)$/,
});

// Stream a large object straight to the response
const stream = storage.getAsStream("videos/intro.mp4");
return new Response(stream);

Custom buckets

import { decorator } from "@talosjs/storage";
import { CloudflareStorage } from "@talosjs/storage";

@decorator.storage()
export class UploadStorage extends CloudflareStorage {}

import { inject } from "@talosjs/container";

export class UploadService {
  constructor(@inject(UploadStorage) private readonly storage: UploadStorage) {}
}

Use in the app

In an @talosjs/app application, storage isn’t a dedicated App config slot. CloudflareStorage registers itself with the container through @decorator.storage() as soon as the class is imported, and you inject it wherever you read or write files.

bun add @talosjs/app @talosjs/storage

Inject it into a service or controller, set the bucket, and use the IStorage methods:

import { inject } from "@talosjs/container";
import { CloudflareStorage } from "@talosjs/storage";

export class MediaService {
  constructor(
    @inject(CloudflareStorage) private readonly storage: CloudflareStorage,
  ) {}

  public async uploadAvatar(userId: string, file: Blob): Promise<void> {
    await this.storage.setBucket("uploads").put(`avatars/${userId}.png`, file);
  }
}

To bind a dedicated R2 bucket to its own injectable type, register a subclass with @decorator.storage():

import { decorator } from "@talosjs/storage";
import { CloudflareStorage } from "@talosjs/storage";

@decorator.storage()
export class AvatarStorage extends CloudflareStorage {}

Set STORAGE_CLOUDFLARE_ACCESS_KEY, STORAGE_CLOUDFLARE_SECRET_KEY, STORAGE_CLOUDFLARE_ENDPOINT, and (optionally) STORAGE_CLOUDFLARE_REGION in your .env.yml (or environment) so the backend can connect.

Exceptions

CloudflareStorage throws StorageException on misconfiguration or a failed operation, carrying a machine-readable key.

Key	When
`CONFIG_REQUIRED`	Missing the access key, secret key, or endpoint.
`STORAGE_UPLOAD_FAILED`	A write failed.
`STORAGE_DOWNLOAD_FAILED`	A read or download failed.
`STORAGE_LIST_FAILED`	Listing a bucket failed.
`FILE_NOT_FOUND`	A read targeted an object that does not exist.

import { StorageException } from "@talosjs/storage";

try {
  await storage.put("avatars/123.png", file);
} catch (error) {
  if (error instanceof StorageException) {
    logger.error(`Storage error [${error.key}]: ${error.message}`, error.data);
  }
  throw error;
}

Working with R2 day to day

Call setBucket() before any read or write, since that call also builds the S3 client for the bucket. Point STORAGE_CLOUDFLARE_ENDPOINT at your account’s R2 S3 endpoint rather than the public bucket URL. Group objects under stable prefixes like avatars/123.png to keep list() and clearBucket() predictable, and prefer getAsStream() and putFile/putDir over loading whole files into memory. Keep the access key, secret key, and endpoint in .env, never in source. When you want a bucket to be injectable on its own, register a CloudflareStorage subclass for it so it carries its own type. See the Storage component for the full interface and the other backends, including Bunny Storage.

Getting Started

AI

Framework

Command Line

Cloudflare Storage

What R2 brings here

Installation

Environment variables

How it works

Usage

Custom buckets

Use in the app

Exceptions

Working with R2 day to day

​What R2 brings here

​Installation

​Environment variables

​How it works

​Usage

​Custom buckets

​Use in the app

​Exceptions

​Working with R2 day to day

What R2 brings here

Installation

Environment variables

How it works

Usage

Custom buckets

Use in the app

Exceptions

Working with R2 day to day