Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

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
nub add files-sdk @bunny.net/storage-sdk
aube add files-sdk @bunny.net/storage-sdk

Usage

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

Limitations

Keys with a . or .. path segment (including the %2e spellings) are rejected before any Storage API call. The Storage API resolves dot segments, so such a key would address a directory or the zone root rather than an object - and delete() on either is recursive.

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 ✅ Idempotent: a missing key is a no-op. The SDK reports a failed DELETE only as false, so the adapter probes the key: if it still exists (say, a read-only access key), the delete throws instead of reporting success.
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.

Was this page helpful?