Adapters

Adapters provide a preconfigured S3 client for your storage provider. Every adapter uses the official AWS S3 SDK (@aws-sdk/client-s3) under the hood — the only difference between adapters is how the client is configured (endpoint, region, credentials, etc.).

Pass an adapter to createStorage to connect vs3 to your provider:

import { createStorage } from "vs3";
import { aws } from "vs3/adapters";

const storage = createStorage({
  bucket: "my-bucket",
  adapter: aws({
    region: "us-east-1",
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
  }),
});

Built-in Adapters

We currently provide built-in support for the following adapters:

• AWS S3
• Backblaze B2
• Cloudflare R2
• DigitalOcean Spaces
• MinIO
• Wasabi

AWS S3

Use aws for standard Amazon S3 buckets.

import { aws } from "vs3/adapters";

const adapter = aws({
  region: "us-east-1",
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

Notes:

• aws(options) accepts AWS SDK S3ClientConfig options, except forcePathStyle.
• Use bucket region values like us-east-1, eu-west-1, ap-southeast-2.

Backblaze B2

Use backblazeB2 for Backblaze B2 S3-compatible buckets.

import { backblazeB2 } from "vs3/adapters";

const adapter = backblazeB2({
  region: "us-west-000",
  credentials: {
    accessKeyId: process.env.B2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.B2_SECRET_ACCESS_KEY!,
  },
});

Notes:

• Endpoint is generated as https://s3.<region>.backblazeb2.com.
• Use the exact B2 region string from your bucket configuration.

Cloudflare R2

Use cloudflareR2 for Cloudflare R2 S3-compatible buckets.

import { cloudflareR2 } from "vs3/adapters";

const adapter = cloudflareR2({
  accountId: process.env.CF_ACCOUNT_ID!,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  },
});

Notes:

• The adapter sets region: "auto" and builds the endpoint from accountId.
• Set jurisdiction only if your R2 account uses data locality constraints.

DigitalOcean Spaces

Use digitaloceanSpaces for DigitalOcean Spaces buckets.

import { digitaloceanSpaces } from "vs3/adapters";

const adapter = digitaloceanSpaces({
  region: "nyc3",
  credentials: {
    accessKeyId: process.env.DO_SPACES_KEY!,
    secretAccessKey: process.env.DO_SPACES_SECRET!,
  },
});

Notes:

• Endpoint is generated as https://<region>.digitaloceanspaces.com.
• The preset uses virtual-host style addressing (forcePathStyle: false).

MinIO

Use minio for self-hosted or managed MinIO instances.

import { minio } from "vs3/adapters";

const adapter = minio({
  endpoint: "http://localhost:9000",
  credentials: {
    accessKeyId: process.env.MINIO_ACCESS_KEY!,
    secretAccessKey: process.env.MINIO_SECRET_KEY!,
  },
});

Notes:

• This preset enables forcePathStyle: true automatically, which MinIO typically requires.
• For local development, keep endpoint/protocol aligned with your MinIO server config.

Wasabi

Use wasabi for Wasabi Hot Cloud Storage buckets.

import { wasabi } from "vs3/adapters";

const adapter = wasabi({
  region: "us-east-1",
  credentials: {
    accessKeyId: process.env.WASABI_ACCESS_KEY!,
    secretAccessKey: process.env.WASABI_SECRET_KEY!,
  },
});

Notes:

• Endpoint is generated as https://s3.<region>.wasabisys.com.
• Keep region and bucket location aligned to avoid signing/endpoint mismatches.

Custom Adapter

Use createAdapter when you need full control over client configuration, or when your provider is not covered by a built-in preset.

Basic Setup

import { S3Client } from "@aws-sdk/client-s3";
import { createAdapter } from "vs3/adapters";

const client = new S3Client({
  endpoint: "https://s3.custom-provider.example",
  region: "us-east-1",
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY!,
    secretAccessKey: process.env.S3_SECRET_KEY!,
  },
});

const adapter = createAdapter({ client });

Why Use This

• your provider requires custom endpoint/signing behavior
• you need extra S3Client settings not covered by a preset
• you already manage an S3Client instance in your app

Utility: generateObjectKey

vs3/adapters also exports generateObjectKey(fileInfo) to create default object keys. Use it as a helper when implementing custom key strategies outside of createStorage.

Next Steps

• Storage Options for generateKey and upload constraints.