Backblaze B2

Backblaze B2 via the S3-compatible API. Endpoint derived from the cluster code (us-west-002, us-east-005, eu-central-003, ...).

Installation

@aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Usage

import { Files } from "files-sdk";
import { backblazeB2 } from "files-sdk/backblaze-b2";

const files = new Files({
  adapter: backblazeB2({
    bucket: "uploads",
    region: "us-west-002", // or "us-east-005", "eu-central-003", ...
    // accessKeyId / secretAccessKey auto-loaded from
    // B2_APPLICATION_KEY_ID / B2_APPLICATION_KEY
  }),
});

Backblaze B2 via its S3-compatible API. A thin wrapper around the S3 adapter - endpoint derived from the cluster code (us-west-002, us-east-005, eu-central-003, …), virtual-hosted-style addressing, errors relabelled. Auto-loads from B2_APPLICATION_KEY_ID and B2_APPLICATION_KEY. Generate an application key in the Backblaze console under Account -> Application Keys; the bucket’s cluster is shown next to its endpoint.

Options

PropType

bucketstring

B2 bucket name. The adapter scopes all operations to it.

Typestring

regionstring

Backblaze B2 cluster code, e.g. `"us-west-000"`, `"us-west-001"`, `"us-west-002"`, `"us-east-004"`, `"us-east-005"`, `"eu-central-003"`. Drives the endpoint host (`https://s3.<region>.backblazeb2.com`); there's no env-var fallback. Doubles as the SigV4 region. The cluster a bucket lives in is shown in the B2 console; pick the wrong one and you'll see a `301` redirect from B2.

Typestring

endpoint?string

Override the B2 endpoint. When unset, defaults to `https://s3.${region}.backblazeb2.com`. B2 routes by Host header — the SDK prepends the bucket subdomain for virtual-hosted style.

Typestring

accessKeyId?string

Static credentials — B2 application key ID. Falls back to `B2_APPLICATION_KEY_ID`; required if that env var isn't set.

Typestring

secretAccessKey?string

Static credentials — B2 application key. Falls back to `B2_APPLICATION_KEY`; required if that env var isn't set.

Typestring

forcePathStyle?boolean

Use path-style addressing (`/<bucket>/<key>`) rather than virtual-hosted style. Defaults to `false` — virtual-hosted is canonical for B2.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing. For public buckets the natural value is the friendly download URL prefix `https://f<NNN>.backblazeb2.com/file/<bucket>` (look it up in the B2 console under your bucket → "Endpoint"), or a custom domain proxied through Cloudflare. When unset, `url()` falls back to a presigned GetObject (default expiry: 1 hour).

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the presigned URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour).

Typenumber

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅
`signedUploadUrl`	✅