Installation

Install files-sdk and the optional peer dependencies for the adapter you're using - anything you don't import is never bundled. ESM only, Node 20+ and Bun.

files-sdk itself is small - a handful of lightweight runtime dependencies (aws4fetch, commander, fflate, mime, p-map, picomatch, and safe-regex2, plus an optional @modelcontextprotocol/sdk for the MCP server) behind a tree of subpath exports. Install the package, then add the peer dependencies for the adapter you’re wiring up. Anything you don’t import is never bundled.

npm install files-sdk

pnpm add files-sdk

yarn add files-sdk

bun add files-sdk

nub add files-sdk

aube add files-sdk

The package ships its own TypeScript types, so there’s no @types/files-sdk to chase down. It’s published as ESM only ("type": "module") and targets modern runtimes - Node 20+ and Bun. From a CommonJS file, reach it with a dynamic import().

Adapter peer dependencies

Adapters are subpath exports - files-sdk/s3, files-sdk/r2, files-sdk/vercel-blob, and so on - and each one’s provider SDK is an optional peer dependency, loaded only when you import that adapter’s subpath. The SDK you don’t import is never bundled, so both install size and cold-start cost stay proportional to the providers you actually wire up.

Install the peer deps for your adapter alongside the SDK. For S3 - and every S3-compatible store, since R2 over HTTP, MinIO, Backblaze, Wasabi, DigitalOcean Spaces, and the rest all wrap the same client:

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

nub add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

aube add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Add @aws-sdk/lib-storage as well if you use multipart or onProgress, or upload a ReadableStream of unknown length, on an S3-family adapter using the AWS SDK client. Without it, those uploads throw a FilesError that names the missing package.

The shape is the same for every adapter, only the packages change: Google Cloud Storage adds @google-cloud/storage; Azure adds @azure/storage-blob (plus @azure/identity only if you build a credential with it); Vercel Blob needs only @vercel/blob. A few adapters need no extra packages at all - files-sdk/fs, files-sdk/memory, and files-sdk/bun-s3 use primitives the runtime already provides, and files-sdk/s3-fetch signs requests with the bundled aws4fetch.

The per-adapter docs list the exact packages for each provider, and the provider catalog exposes the same data programmatically (peerDeps) if you’re generating install commands or building a config UI.

Missing a peer dependency?

Import an adapter without its peer installed and Node throws ERR_MODULE_NOT_FOUND naming the package that’s missing - the SDK doesn’t vendor or shim provider clients, so the failure is loud and specific rather than a silent fallback. Install the named package and the import resolves. R2, MinIO, and RustFS are the exception: they load the AWS SDK lazily (so a client: "fetch" bundle never pulls it in), so the missing-module error arrives on the first call instead, as the cause of a FilesError.

Once your adapter’s packages are in place, head to Usage to construct a Files instance and run the core methods.