Amazon S3

AWS S3 (and any S3-compatible bucket). Uses the standard AWS credential chain - environment, IAM role, shared profile.

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

To report true byte-level upload progress via upload’s onProgress option, also install @aws-sdk/lib-storage — it’s optional and only loaded when onProgress is used.

Usage

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = new Files({
  adapter: s3({
    bucket: "uploads",
    region: "us-east-1",
    // credentials auto-loaded from the AWS chain
    // (env vars, IAM role, shared profile, ...)
  }),
});

Options

PropType

bucketstring

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

Typestring

region?string

AWS region the bucket lives in (e.g. `us-east-1`). Falls back to `AWS_REGION`; required if no env var is set.

Typestring

endpoint?string

Override the S3 service endpoint. Use this to point at S3-compatible services (DigitalOcean Spaces, Wasabi, Backblaze B2, LocalStack, etc.).

Typestring

forcePathStyle?boolean

Use path-style addressing (`https://endpoint/bucket/key`) instead of virtual-hosted style (`https://bucket.endpoint/key`). Required by some S3-compatible services and by LocalStack.

Typeboolean

credentials?

{
    accessKeyId: string;
    secretAccessKey: string;
    sessionToken?: string;
  }

Static credentials. Skip to use the AWS credential chain (env vars, IAM role, shared profile, EC2/ECS/EKS instance metadata).

Type

{
    accessKeyId: string;
    secretAccessKey: string;
    sessionToken?: string;
  }

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing — appropriate for buckets fronted by a CDN, public-read policy, or custom domain. When unset, `url()` falls back to a presigned `GetObject` URL (see {@link defaultUrlExpiresIn}). The base is concatenated as-is. Trailing slashes are tolerated. Keys are embedded literally — caller is responsible for URL-encoding untrusted segments.

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the presigned URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour). Per-call `url(key, { expiresIn })` overrides.

Typenumber

defaultProviderMessage?string

Override the fallback message used when an unknown error has no `message` of its own. Internal — set by the r2-http adapter so its users see "R2 error" instead of "S3 error".

Typestring

Compatibility

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