Filebase

Filebase via the S3-compatible API. Fronts decentralized networks (IPFS, Sia, Storj) chosen per-bucket.

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 { filebase } from "files-sdk/filebase";

const files = new Files({
  adapter: filebase({
    bucket: "uploads",
    // accessKeyId / secretAccessKey auto-loaded from
    // FILEBASE_ACCESS_KEY_ID / FILEBASE_SECRET_ACCESS_KEY
  }),
});

Filebase via its S3-compatible API. Filebase fronts decentralized storage networks (IPFS, Sia, Storj) behind a standard S3 gateway - the network is chosen per-bucket in the dashboard, not per-request. A thin wrapper around the S3 adapter pointed at https://s3.filebase.com, with errors relabelled. Auto-loads from FILEBASE_ACCESS_KEY_ID and FILEBASE_SECRET_ACCESS_KEY. Generate access keys in the Filebase console under Access Keys.

Options

PropType

bucketstring

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

Typestring

endpoint?string

Filebase S3 endpoint. Defaults to `https://s3.filebase.com` — Filebase runs a single global S3-compatible gateway that fronts IPFS, Sia, and Storj storage networks (the network is chosen per-bucket in the dashboard, not per-request).

Typestring

accessKeyId?string

Static credentials. Falls back to `FILEBASE_ACCESS_KEY_ID`; required if that env var isn't set.

Typestring

secretAccessKey?string

Static credentials. Falls back to `FILEBASE_SECRET_ACCESS_KEY`; required if that env var isn't set.

Typestring

region?string

SigV4 region. Defaults to `"us-east-1"`. Filebase ignores it for routing but the SigV4 signature still requires *some* value.

Typestring

forcePathStyle?boolean

Use path-style addressing (`/<bucket>/<key>`) rather than virtual-hosted style. Defaults to `false` — Filebase supports virtual-hosted style on the bucket subdomain (`<bucket>.s3.filebase.com`).

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing. Filebase serves public objects via per-network gateways (e.g. an IPFS CID gateway); the natural value is whatever gateway URL the dashboard exposes for your bucket. 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`	✅