Bunny Storage

BunnyStorage is the Storage component’s Bunny backend. It implements the IStorage interface directly against the Bunny Storage SDK, uploading and downloading files to a regional storage zone over HTTPS. That makes it a good fit for edge file delivery paired with Bunny’s CDN. Because it shares the IStorage contract with the filesystem and S3-compatible backends, you can switch to or from Bunny without changing a single call site.

What this backend gives you

Your files live in a Bunny Storage zone close to your users and pair naturally with Bunny’s CDN. The interface is the same IStorage you already know: put, getFile, getAsJson, delete, list, and the rest, identical to every other storage backend. You choose from nine storage regions with a short region code. put() takes a range of inputs (strings, ArrayBuffer, Blob, Request/Response, and BunFile/S3File) and converts each to a stream for upload. The class registers with @decorator.storage() and resolves from the container.

Installation

BunnyStorage ships with @talosjs/storage and depends on the Bunny Storage SDK.

bun add @talosjs/storage @bunny.net/storage-sdk

Environment variables

Variable	Required	Purpose
`STORAGE_BUNNY_ACCESS_KEY`	Yes	Bunny storage access key. Missing throws `StorageException` (`API_KEY_REQUIRED`).
`STORAGE_BUNNY_STORAGE_ZONE`	Yes	Bunny storage zone name. Missing throws `StorageException` (`STORAGE_ZONE_REQUIRED`).
`STORAGE_BUNNY_REGION`	No	Region code. Defaults to `de`.

STORAGE_BUNNY_ACCESS_KEY=your_access_key
STORAGE_BUNNY_STORAGE_ZONE=your-zone
STORAGE_BUNNY_REGION=de

Credentials are validated when BunnyStorage is constructed, so a missing key or zone fails fast at startup.

Regions

STORAGE_BUNNY_REGION accepts a short code that maps to a Bunny storage region:

Code	Region
`de`	Falkenstein (default)
`uk`	London
`ny`	New York
`la`	Los Angeles
`sg`	Singapore
`se`	Stockholm
`br`	São Paulo
`jh`	Johannesburg
`syd`	Sydney

How it works

BunnyStorage connects to your storage zone with the access key and chosen region, then organizes files under a bucket. The active bucket becomes a path prefix: with bucket uploads, a key avatars/1.png is stored at /uploads/avatars/1.png. Content passed to put() is converted to a ReadableStream and uploaded through the Bunny SDK. Reads stream back and are materialized as JSON, an ArrayBuffer, a stream, or written to disk.

Method	Purpose
`getBucket()` / `setBucket(name)`	Read or switch the active bucket (path prefix); `setBucket` chains.
`list()`	List the file object names in the current bucket.
`clearBucket()`	Delete every file in the current bucket.
`exists(key)`	Whether an object exists.
`delete(key)`	Remove one object (no-op if absent).
`put(key, content)`	Upload 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 { BunnyStorage } from "@talosjs/storage";

const storage = container.get(BunnyStorage).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);

Use in the app

In an @talosjs/app application, storage isn’t a dedicated App config slot. BunnyStorage 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 @bunny.net/storage-sdk

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

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

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

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

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

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

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

Set STORAGE_BUNNY_ACCESS_KEY, STORAGE_BUNNY_STORAGE_ZONE, and (optionally) STORAGE_BUNNY_REGION in your .env.yml (or environment) so the backend can connect.

Exceptions

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

Key	When
`API_KEY_REQUIRED`	Constructed without `STORAGE_BUNNY_ACCESS_KEY`.
`STORAGE_ZONE_REQUIRED`	Constructed without `STORAGE_BUNNY_STORAGE_ZONE`.
`STORAGE_UPLOAD_FAILED`	An upload to the storage zone failed.
`STORAGE_DOWNLOAD_FAILED`	A download or read failed.
`STORAGE_LIST_FAILED`	Listing the zone failed.
`UNSUPPORTED_CONTENT_TYPE`	`put()` received content it cannot convert to a stream.

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;
}

Keeping uploads predictable

Call setBucket() before any read or write so keys land under the right path prefix. Set STORAGE_BUNNY_REGION to the zone closest to your users to keep latency down. Group objects under stable prefixes like avatars/123.png, which keeps list() and clearBucket() predictable. For anything large, reach for getAsStream() and putFile/putDir instead of loading whole files into memory, and pass a filter regex to putDir() when you only want a subset of a directory. Keep the access key and zone in .env rather than hard-coding them. See the Storage component for the full interface and the other backends, including Cloudflare Storage.

Getting Started

AI

Framework

Command Line

Bunny Storage

What this backend gives you

Installation

Environment variables

Regions

How it works

Usage

Use in the app

Exceptions

Keeping uploads predictable

​What this backend gives you

​Installation

​Environment variables

​Regions

​How it works

​Usage

​Use in the app

​Exceptions

​Keeping uploads predictable

What this backend gives you

Installation

Environment variables

Regions

How it works

Usage

Use in the app

Exceptions

Keeping uploads predictable