Bunny Storage

Bunny Storage via @bunny.net/storage-sdk. Connects to a Storage Zone with its zone password / access key, auto-loading the BUNNY_STORAGE_* env vars.

Installation

@bunny.net/storage-sdk is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @bunny.net/storage-sdk

pnpm add files-sdk @bunny.net/storage-sdk

yarn add files-sdk @bunny.net/storage-sdk

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

Bunny Storage via the official @bunny.net/storage-sdk. The adapter connects to a Storage Zone with its zone password / API access key and uses Bunny’s HTTP Storage API for reads, writes, listing, and deletes. Auto-loads from BUNNY_STORAGE_ZONE, BUNNY_STORAGE_ACCESS_KEY, and BUNNY_STORAGE_REGION; also accepts STORAGE_ZONE, STORAGE_ACCESS_KEY, and STORAGE_REGION as aliases (the names used in the Bunny SDK’s README example).

import { Files } from "files-sdk";
import { bunnyStorage } from "files-sdk/bunny-storage";

const files = new Files({
  adapter: bunnyStorage({
    zone: "uploads",
    region: "de",
    // accessKey auto-loaded from BUNNY_STORAGE_ACCESS_KEY
    // publicBaseUrl: "https://files.example.com",
  }),
});

Options

PropType

zone?string

Bunny Storage zone name. Falls back to `BUNNY_STORAGE_ZONE`, then `STORAGE_ZONE` (the convention used in the SDK's README example).

Typestring

accessKey?string

Bunny Storage zone password / API access key. Falls back to `BUNNY_STORAGE_ACCESS_KEY`, then `STORAGE_ACCESS_KEY` (the convention used in the SDK's README example).

Typestring

region?BunnyStorageRegion

Primary Bunny Storage region. Pass one of `BunnyStorageSDK.regions.StorageRegion.*`, e.g. `"de"`, `"ny"`, `"syd"`. Falls back to `BUNNY_STORAGE_REGION`, then `STORAGE_REGION`.

TypeBunnyStorageRegion

client?BunnyStorageClient

Existing connected storage zone from `@bunny.net/storage-sdk`. Highest precedence; when provided, `zone`, `accessKey`, and `region` are ignored.

TypeBunnyStorageClient

publicBaseUrl?string

Origin used to build URLs from `url()`, typically a Bunny Pull Zone or custom CDN hostname in front of the Storage Zone. When unset, `url()` throws because the Storage API requires an `AccessKey` header and has no signed-read URL primitive.

Typestring

Compatibility

Method	Status	Notes
`upload`	⚠️	Custom `metadata` and `cacheControl` throw — the Bunny Storage TypeScript SDK exposes content-type/checksum but no arbitrary object metadata or per-object cache-control field. Configure cache behavior on the Pull Zone/CDN. Resumable uploads (`control`) are not supported — Bunny Storage uploads in a single PUT.
`download`	✅
`delete`	✅
`list`	⚠️	Bunny lists a directory, not a recursive object-prefix scan. The adapter chooses the nearest directory for `prefix`, filters that page client-side, and encodes numeric offsets as cursors after fetching the directory listing.
`search`	⚠️	Built on `listAll` — inherits this adapter’s `list` behavior above. Client-side key match (glob, regex, substring, exact).
`head`	✅
`exists`	✅
`copy`	⚠️	Read-then-write — Bunny Storage’s TypeScript SDK has no server-side copy primitive, so the source is downloaded and re-uploaded. Not server-side atomic.
`url`	⚠️	Requires `publicBaseUrl` (for example a Bunny Pull Zone or custom CDN hostname) and returns `<publicBaseUrl>/<key>`. Without it, throws because the Storage API URL requires an `AccessKey` header. `expiresIn` is ignored and `responseContentDisposition` throws — Bunny Storage has no signed-read URL primitive.
`signedUploadUrl`	❌	Throws — Bunny Storage has no presigned upload primitive. Writes go through the Storage API with an `AccessKey` header, so upload server-side via the SDK or proxy through your application.

Bunny Storage

Installation

Usage

Options

Compatibility