DigitalOcean Spaces

DigitalOcean Spaces via the S3-compatible API. Endpoint derived from the region, virtual-hosted addressing.

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

const files = new Files({
  adapter: digitaloceanSpaces({
    bucket: "uploads",
    region: "nyc3",
    // accessKeyId / secretAccessKey auto-loaded from
    // DO_SPACES_KEY / DO_SPACES_SECRET
  }),
});

Options

PropType

bucketstring

Spaces name. The adapter scopes all operations to it.

Typestring

regionstring

Spaces datacenter region, e.g. `"nyc3"`, `"sfo3"`, `"ams3"`, `"fra1"`, `"sgp1"`, `"syd1"`, `"blr1"`, `"tor1"`, `"lon1"`. Drives the endpoint host; there's no env-var fallback (no `DO_REGION` convention).

Typestring

endpoint?string

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

Typestring

accessKeyId?string

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

Typestring

secretAccessKey?string

Static credentials. Falls back to `DO_SPACES_SECRET`; 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 Spaces.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing — typical values are the Spaces CDN host (`https://${bucket}.${region}.cdn.digitaloceanspaces.com`) or a custom CNAME. 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`	✅