@storagesdk/adapters

Backend adapters for storagesdk. Import the adapter you need via a subpath; the others are tree-shaken out.

npm install @storagesdk/core @storagesdk/adapters

Each provider's SDK is an optional peer dependency. Install only the SDKs for adapters you actually import — see each adapter's README for the exact install line.

Available adapters

| Adapter | Subpath | Backend | | --- | --- | --- | | Tigris | @storagesdk/adapters/tigris | Tigris — snapshots and forks are first-class via Tigris's native APIs. | | S3 | @storagesdk/adapters/s3 | Amazon S3 and any S3-compatible provider. | | R2 | @storagesdk/adapters/r2 | Cloudflare R2. | | Code Storage | @storagesdk/adapters/code-storage | Code Storage repositories — snapshots are tags, forks are branches. | | Archil | @storagesdk/adapters/archil | Archil disks via Archil's S3-compatible API. | | Mesa | @storagesdk/adapters/mesa | Mesa repositories — snapshots and forks are bookmarks. | | GCS | @storagesdk/adapters/gcs | Google Cloud Storage. | | Azure Blob | @storagesdk/adapters/azure | Azure Blob Storage. | | Vercel Blob | @storagesdk/adapters/vercel | Vercel Blob. | | MinIO | @storagesdk/adapters/minio | MinIO. | | GitHub | @storagesdk/adapters/github | GitHub repository — snapshots are tags, forks are branches, native git refs all the way down. | | WebDAV | @storagesdk/adapters/webdav | Any WebDAV server — Nextcloud, ownCloud, Apache mod_dav, nginx-dav, NAS, pCloud, mailbox.org, kDrive. Snapshots/forks via native server-side COPY. | | Fly.io | @storagesdk/adapters/fly | Fly-managed Tigris buckets — branded alias of the Tigris adapter. | | Railway | @storagesdk/adapters/railway | Railway Buckets — branded alias of the Tigris adapter. | | Filesystem | @storagesdk/adapters/fs | Local node:fs/promises. For development and tests. |

For the full, up-to-date list see storagesdk.dev/adapters.

Runtime adapter selection

For CLIs, scripts, and anywhere the adapter is picked from a string at runtime, the package's root export ships a small registry: enumerate every shipped adapter, introspect its env-var spec, build the adapter.

import {
  ADAPTERS,
  type AdapterName,
  type AdapterEnvVar,
  buildAdapter,
  getAdapterEnvVars,
} from '@storagesdk/adapters';

// Enumerate
ADAPTERS
// → readonly ['fs', 's3', 'r2', 'archil', 'code-storage', 'mesa', 'minio', 'tigris', 'azure', 'gcs',
//             'vercel', 'github', 'webdav', 'backblaze', 'spaces',
//             'wasabi', 'supabase', 'linode', 'fly', 'railway']

// What env vars does this adapter read?
getAdapterEnvVars('tigris')
// → [{ name: 'TIGRIS_BUCKET', required: true }, ...]

// Read env config + dynamically import the factory + construct.
const adapter = await buildAdapter('tigris');
const storage = new Storage({ adapter });

Each adapter reads <NAME>_* env vars matching its config shape, with backend-native fallbacks where they exist (S3 falls back to AWS_*, GCS to GOOGLE_CLOUD_PROJECT / GOOGLE_APPLICATION_CREDENTIALS, Vercel Blob to BLOB_READ_WRITE_TOKEN, Azure to AZURE_STORAGE_ACCOUNT / AZURE_STORAGE_KEY).

buildAdapter is async because it import()s only the adapter you request — peer-SDK code (@aws-sdk/client-s3, @azure/storage-blob, etc.) stays out of the static bundle until needed. ADAPTERS and getAdapterEnvVars are sync.

Library consumers using a single adapter via the subpath import (@storagesdk/adapters/tigris) are unaffected — the registry is purely additive for runtime-driven use cases.

See storagesdk.dev/adapters for the full env-var reference.

Snapshots and forks

Every adapter implements snapshots and forks against the same contract. Backends that don't offer native primitives use a sibling-bucket / sibling-container convention (server-side copy + a per-bucket manifest); Tigris uses its native snapshot/fork APIs.

See each adapter's README for the specifics — naming convention, what the manifest contains, and what's enforced server-side vs in the SDK.

Conformance suite

@storagesdk/adapters/test-suite exports the cross-adapter behavioral suite (upload round-trip, NotFound semantics, snapshot/fork contract, AbortSignal short-circuit, etc.). Drop it into your own adapter's test file to verify you're spec-compliant. See the top-level README's "Authoring adapters" section for details.