files-sdk.dev

mx

ns

vick.ns.cloudflare.com

zara.ns.cloudflare.com

caa

txt

google-site-verification=JdGWdIflxdk6fnmnc2osI7G14eA7OdjE-IVQ6kSC85Q

dmarc

User-agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=yes
Allow: /

Sitemap: https://files-sdk.dev/sitemap.xml

# Files SDK

> A unified storage SDK for object and blob backends. One small, honest API. Web-standard I/O. An escape hatch when you need the native client.

Reach for Files SDK when a TypeScript or JavaScript project needs to store files in object or blob storage without locking into one provider: uploads and downloads, signed URLs, listing and search, multipart and resumable uploads, and moving data between providers. One `Files` class runs the same methods on 48 adapters (Cloudflare R2, Amazon S3 and every S3-compatible store, Google Cloud Storage, Azure Blob, Vercel Blob, Supabase, the local filesystem, and more). Each adapter is its own subpath export with its provider's SDK as an optional peer.

Install with `npm i files-sdk`, construct `new Files({ adapter: r2({ bucket }) })`, and call `upload`, `download`, `list`, `url`, and the rest. Plugins such as `files-sdk/encryption` and `files-sdk/validation` wrap the same API. `files-sdk/api` with a framework binding (`files-sdk/next`, `files-sdk/hono`, …) serves browser uploads behind an `authorize` hook, and the `files` CLI and its MCP server expose the same operations to scripts and agents. The `files-sdk` agent skill below covers setup and usage, and the guides under /guides walk through complete workflows end to end: browser uploads, private downloads, AI attachments and storage tools, provider setup, and migrations.

## Changelog

- [files-sdk@3.1.1](https://files-sdk.dev/changelog/files-sdk-3-1-1): Interrupting a buffered DownloadedFile read in files-sdk/effect (text, arrayBuffer, or blob) now cancels the body read underneath, instead of leaving it…
- [files-sdk@3.1.0](https://files-sdk.dev/changelog/files-sdk-3-1-0): Add an Effect v4 bridge (files-sdk/effect). Files is a Context.Service provided by Files.layer(), from a Files instance or the options to build one. Its…
- [files-sdk@3.0.0](https://files-sdk.dev/changelog/files-sdk-3-0-0): files-sdk/cache no longer shares entries between instances. Store keys now include the instance prefix, and a custom store requires a namespace naming the…
- [files-sdk@2.6.2](https://files-sdk.dev/changelog/files-sdk-2-6-2): files-sdk/client download() now reports a failure at the storage host, after the gateway redirected to a signed URL, with the code its HTTP status implies…
- [files-sdk@2.6.1](https://files-sdk.dev/changelog/files-sdk-2-6-1): The downloadFile tool in files-sdk/ai-sdk, files-sdk/openai, and files-sdk/claude now enforces maxBytes on the bytes it actually reads. It used to check only…
- [files-sdk@2.6.0](https://files-sdk.dev/changelog/files-sdk-2-6-0): Add a RustFS adapter (files-sdk/rustfs). RustFS is the Apache-2.0 Rust object store that runs as a MinIO drop-in, and rustfs() mirrors the minio() adapter…
- [files-sdk@2.5.0](https://files-sdk.dev/changelog/files-sdk-2-5-0): Support Vercel Blob Signed URLs in the vercelBlob() adapter. In access: "private" mode, url() now mints a presigned GET scoped to the key that honors…
- [files-sdk@2.4.1](https://files-sdk.dev/changelog/files-sdk-2-4-1): softDelete() and versioning() can now be composed on one instance. Both plugins contributed a restore extension, so createFiles({ plugins: [softDelete()…
- [files-sdk@2.4.0](https://files-sdk.dev/changelog/files-sdk-2-4-0): minio: add the client: "fetch" engine (#155). minio({ client: "fetch" }) runs on the same SigV4-signed aws4fetch core as r2({ client: "fetch" }) and s3Fetch()…
- [files-sdk@2.3.1](https://files-sdk.dev/changelog/files-sdk-2-3-1): Fix the files-sdk/api proxy download returning a 500 for a suffix Range request (bytes=-N) against an empty object. The header resolved to an inverted byte…
- [files-sdk@2.3.0](https://files-sdk.dev/changelog/files-sdk-2-3-0): Add provider-native conditional create, replace, exact-read, delete, and copy operations to the existing plugin, hook, retry, prefix, read-only, and receipt…
- [files-sdk@2.2.5](https://files-sdk.dev/changelog/files-sdk-2-2-5): Content-type inference from file names (Dropbox, FTP, SFTP, WebDAV, Box, unzip, CLI directory uploads) now uses the mime package's full table instead of a…
- [files-sdk@2.2.4](https://files-sdk.dev/changelog/files-sdk-2-2-4): Request httpMetadata and customMetadata when listing through the R2 Workers binding, so list() reports the stored content type and metadata instead of…
- [files-sdk@2.2.3](https://files-sdk.dev/changelog/files-sdk-2-2-3): Preserve the caller's query string on gateway-minted proxy upload targets, so a per-request files factory selected via the endpoint query (e.g. useFiles({…
- [files-sdk@2.2.2](https://files-sdk.dev/changelog/files-sdk-2-2-2): Avoid loading Firebase Admin when the Firebase Storage adapter receives an initialized bucket.Refresh environment-provided Vercel Blob credentials for every…
- [files-sdk@2.2.1](https://files-sdk.dev/changelog/files-sdk-2-2-1): Expose the lazy provider-aware loadFiles runtime loader through files-sdk/loader.Keep @aws-sdk/* out of the static module graph reachable from files-sdk/r2 so…
- [files-sdk@2.2.0](https://files-sdk.dev/changelog/files-sdk-2-2-0): Add first-class NestJS support (#95). New files-sdk/nestjs subpath exports a dynamic FilesModule (forRoot() / forRootAsync()) that configures the gateway…
- [files-sdk@2.1.0](https://files-sdk.dev/changelog/files-sdk-2-1-0): Add files-sdk/tanstack-start server adapter — createRouteHandler mounts the Files gateway in a TanStack Start server route (server.handlers).Add a WebDAV…
- [files-sdk@2.0.0](https://files-sdk.dev/changelog/files-sdk-2-0-0): Release files-sdk 2.0 — the full-stack release. Alongside the core Files API, the SDK now reaches the browser with framework client bindings (files-sdk/react…
- [files-sdk@1.9.0](https://files-sdk.dev/changelog/files-sdk-1-9-0): Add an audit() plugin at files-sdk/audit that writes a structured who/what/when record of every mutation to an awaited sink — the durable, awaitable…
- [files-sdk@1.8.0](https://files-sdk.dev/changelog/files-sdk-1-8-0): Add a compression() plugin at files-sdk/compression for transparent, at-rest compression. Bodies are gzipped (or deflate / deflate-raw) on upload with the…
- [files-sdk@1.7.0](https://files-sdk.dev/changelog/files-sdk-1-7-0): Add sync() — an incremental, optionally-pruning mirror between two providers. It skips objects already identical at the destination (compare by size + etag…
- [files-sdk@1.6.0](https://files-sdk.dev/changelog/files-sdk-1-6-0): Bring the CLI (and MCP server) to full parity with the SDK surface.Every Files capability is now reachable from the files binary:Global --key-prefix scopes…
- [files-sdk@1.5.0](https://files-sdk.dev/changelog/files-sdk-1-5-0): upload, download, head, and exists now accept an array for bulk operations, mirroring delete. Pass the usual single argument for the original behavior…
- [files-sdk@1.4.0](https://files-sdk.dev/changelog/files-sdk-1-4-0): Add Alibaba Cloud Object Storage Service (OSS) adapter (files-sdk/alibaba). Thin wrapper around the S3 adapter — endpoint derived from the region code…
- [files-sdk@1.3.0](https://files-sdk.dev/changelog/files-sdk-1-3-0): Add Appwrite adapter at files-sdk/appwrite exporting appwrite(), a wrapper around the official node-appwrite SDK's Storage API. Auto-loads endpoint…
- [files-sdk@1.2.0](https://files-sdk.dev/changelog/files-sdk-1-2-0): Add AI SDK tools subpath (files-sdk/ai-sdk) exporting createFileTools(...) — wraps a configured Files instance as a set of Vercel AI SDK tools (listFiles…
- [files-sdk@1.1.2](https://files-sdk.dev/changelog/files-sdk-1-1-2): googleDrive and onedrive adapters now auto-load credentials from process.env when not passed explicitly, matching the convention already in place for the…
- [files-sdk@1.1.1](https://files-sdk.dev/changelog/files-sdk-1-1-1): Fix release workflow referencing a non-existent VERCEL_PROJECT_ID_WEB secret; now reads VERCEL_PROJECT_ID to match the configured repository secret so the…
- [files-sdk@1.1.0](https://files-sdk.dev/changelog/files-sdk-1-1-0): Add Akamai Cloud Object Storage adapter (files-sdk/akamai), formerly Linode Object Storage. Thin wrapper over the S3 adapter with Akamai defaults: endpoint…
- [files-sdk@1.0.0](https://files-sdk.dev/changelog/files-sdk-1-0-0): Initial release

## Docs

- [Introduction](https://files-sdk.dev/docs): Files SDK is a unified storage API with 48 adapters - one class, eleven methods, a typed escape hatch, and an agent-friendly CLI.
- [FAQ](https://files-sdk.dev/docs/faq): Common questions about supported providers, bundling and peer dependencies, switching backends, browser uploads, error handling, and the CLI.
- [Installation](https://files-sdk.dev/docs/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 22+ and Bun.
- [Migrating to v3](https://files-sdk.dev/docs/migrating-to-v3): What changed in files-sdk 3.0 - body-less head and list results, two new error codes, one bulk result shape, expiring URLs that never silently stay permanent, a capabilities object for adapters, and Node 22.
- [Providers](https://files-sdk.dev/docs/providers): A zero-dependency catalog of every provider the SDK ships and the env vars each one reads - for building config UIs, sync engines, and onboarding flows.
- [Troubleshooting](https://files-sdk.dev/docs/troubleshooting): Common errors, the normalized FilesError code model, adapter-specific gotchas, and debugging tips for resolving issues across every Files SDK backend.
- [Usage](https://files-sdk.dev/docs/usage): Construct a Files instance with an adapter, then call the same eleven methods on it - swap the adapter to switch backends.

### Adapters

- [Adapters](https://files-sdk.dev/docs/adapters): Compare the 48 storage backends Files SDK supports, from Cloudflare R2 and S3 to Vercel Blob and the local filesystem, by what each one can do.

#### System Adapters

- [Filesystem](https://files-sdk.dev/docs/adapters/fs): Local filesystem - the dev/test adapter. Uses node:fs/promises with a sidecar .meta.json per file. Not for production.
- [FTP](https://files-sdk.dev/docs/adapters/ftp): FTP / FTPS via basic-ftp. Node-only. Connect-per-operation with an injectable client for batch work; url() needs an HTTP front.
- [In-Memory](https://files-sdk.dev/docs/adapters/memory): In-memory store backed by a Map - the test/reference adapter. Zero dependencies, isomorphic, and non-persistent. Ideal for unit tests; not for production.
- [SFTP](https://files-sdk.dev/docs/adapters/sftp): SFTP (SSH File Transfer Protocol) via ssh2-sftp-client. Node-only. Connect-per-operation with an injectable client for batch work; url() needs an HTTP front.
- [WebDAV](https://files-sdk.dev/docs/adapters/webdav): WebDAV (Nextcloud, ownCloud, Apache mod_dav, …) via the webdav client. HTTP-based, with native server-side copy/move; url() needs an HTTP front.

#### Vendor Adapters

- [Akamai Cloud Object Storage](https://files-sdk.dev/docs/adapters/akamai): Akamai Cloud Object Storage (formerly Linode) via the S3-compatible API. Endpoint derived from the region/cluster code.
- [Alibaba Cloud OSS](https://files-sdk.dev/docs/adapters/alibaba): Alibaba Cloud Object Storage Service (OSS) via the S3-compatible API. Endpoint derived from the region code (cn-hangzhou, ap-southeast-1, ...).
- [Amazon S3](https://files-sdk.dev/docs/adapters/s3): AWS S3 (and any S3-compatible bucket). Uses the standard AWS credential chain - environment, IAM role, shared profile.
- [Appwrite](https://files-sdk.dev/docs/adapters/appwrite): Appwrite Storage via the official node-appwrite SDK. Auto-loads APPWRITE_ENDPOINT, APPWRITE_PROJECT_ID, and APPWRITE_API_KEY, or pass an existing client.
- [Archil](https://files-sdk.dev/docs/adapters/archil): Archil disks via the S3-compatible API. The disk id is the bucket and the endpoint is derived from the Archil region. Supports branch-scoped access.
- [Azure Blob Storage](https://files-sdk.dev/docs/adapters/azure): Azure Blob Storage via @azure/storage-blob. Five credential modes - connection string, account key, token credential, SAS token, or anonymous.
- [Backblaze B2](https://files-sdk.dev/docs/adapters/backblaze-b2): Backblaze B2 via the S3-compatible API. Endpoint derived from the cluster code (us-west-002, us-east-005, eu-central-003, ...).
- [Box](https://files-sdk.dev/docs/adapters/box): Box via the official typed SDK. Translates virtual keys into nested folders under a configurable rootFolderId.
- [Bun S3](https://files-sdk.dev/docs/adapters/bun-s3): Upload, download, list, and presign files with Bun's native Bun.S3Client on AWS S3, Cloudflare R2, MinIO, or any S3-compatible bucket, with no AWS SDK.
- [Bunny Storage](https://files-sdk.dev/docs/adapters/bunny-storage): Bunny Storage via @bunny.net/storage-sdk. Connects to a Storage Zone with its zone password / access key, auto-loading the BUNNY_STORAGE_* env vars.
- [Cloudflare R2](https://files-sdk.dev/docs/adapters/r2): Cloudflare R2 over the S3-compatible HTTP API. Auto-loads R2_* env vars or accepts an R2Bucket binding inside Workers.
- [Cloudinary](https://files-sdk.dev/docs/adapters/cloudinary): Cloudinary asset CDN via the official Node SDK. Defaults to resource_type: raw for arbitrary-bytes storage; switch to image/video for transforms.
- [Convex](https://files-sdk.dev/docs/adapters/convex): Convex file storage via the function context (ctx.storage). Runs inside Convex actions/mutations/queries; the Convex-assigned storage id is the key.
- [DigitalOcean Spaces](https://files-sdk.dev/docs/adapters/digitalocean-spaces): DigitalOcean Spaces via the S3-compatible API. Endpoint derived from the region, virtual-hosted addressing, keys auto-loaded from DO_SPACES_KEY/SECRET.
- [Dropbox](https://files-sdk.dev/docs/adapters/dropbox): Dropbox via the official SDK. Path-addressable, so virtual keys map directly to Dropbox paths - no cache, with OAuth refresh-token and access-token auth.
- [Exoscale Object Storage](https://files-sdk.dev/docs/adapters/exoscale): Exoscale Object Storage (SOS) via the S3-compatible API. Endpoint derived from the zone code (ch-gva-2, de-fra-1, ...).
- [Filebase](https://files-sdk.dev/docs/adapters/filebase): Filebase via the S3-compatible API. Fronts decentralized storage networks (IPFS, Sia, Storj) chosen per-bucket in the dashboard, not per-request.
- [Firebase Storage](https://files-sdk.dev/docs/adapters/firebase-storage): Firebase Cloud Storage via the official firebase-admin SDK. Underlying client is @google-cloud/storage, so V4 signed URLs and POST policy uploads come for free.
- [Google Cloud Storage](https://files-sdk.dev/docs/adapters/gcs): Google Cloud Storage via the official @google-cloud/storage SDK. Application Default Credentials by default, resumable uploads when onProgress is passed.
- [Google Drive](https://files-sdk.dev/docs/adapters/google-drive): Google Drive via the official Drive v3 client. Maps unified string keys onto Drive's appProperties with a per-instance LRU cache.
- [Hetzner Object Storage](https://files-sdk.dev/docs/adapters/hetzner): Use Hetzner Object Storage from Node.js - endpoint from the fsn1, nbg1, or hel1 location, HCLOUD_* keys, uploads, listing, and presigned URLs.
- [IBM Cloud Object Storage](https://files-sdk.dev/docs/adapters/ibm-cos): IBM Cloud Object Storage via the S3-compatible API. Endpoint derived from the region code, auth uses IBM Cloud HMAC credentials, not IAM API keys.
- [iDrive e2](https://files-sdk.dev/docs/adapters/idrive-e2): iDrive e2 via the S3-compatible API. Endpoint required (iDrive hostnames are tied to the cluster your bucket lives in).
- [MinIO](https://files-sdk.dev/docs/adapters/minio): MinIO and other self-hosted S3-compatible servers. Path-style addressing on by default; region defaulted; errors relabelled; optional @aws-sdk-free fetch client for Workers.
- [Neon](https://files-sdk.dev/docs/adapters/neon): Neon branchable object storage via the S3-compatible API. neon dev / neon env pull inject the AWS_* env vars; path-style addressing is required.
- [Netlify Blobs](https://files-sdk.dev/docs/adapters/netlify-blobs): Netlify Blobs via @netlify/blobs. Auto-detects siteID and token on Netlify runtimes; falls back to env vars elsewhere.
- [OneDrive](https://files-sdk.dev/docs/adapters/onedrive): OneDrive and SharePoint document libraries via Microsoft Graph. Path-addressable with no virtual-key bookkeeping, chunked upload sessions past 250 MB.
- [Oracle Cloud Object Storage](https://files-sdk.dev/docs/adapters/oracle-cloud): Oracle Cloud Infrastructure Object Storage via the S3 compatibility layer. Auth uses HMAC Customer Secret Keys, not regular API keys.
- [OVHcloud Object Storage](https://files-sdk.dev/docs/adapters/ovhcloud): OVHcloud Object Storage via the S3-compatible API. Endpoint derived from the region code.
- [PocketBase](https://files-sdk.dev/docs/adapters/pocketbase): PocketBase via the official JS SDK. Maps the unified key/blob API onto a dedicated collection with a unique key field and a single-file body field.
- [RustFS](https://files-sdk.dev/docs/adapters/rustfs): RustFS, the Apache-2.0 Rust object store that runs as a MinIO drop-in. Path-style addressing on by default; region defaulted; errors relabelled; optional @aws-sdk-free fetch client for Workers.
- [S3 (fetch)](https://files-sdk.dev/docs/adapters/s3-fetch): AWS S3 and any S3-compatible bucket over a SigV4-signed fetch engine - no @aws-sdk/* packages, built for Cloudflare Workers and other edge runtimes.
- [Scaleway Object Storage](https://files-sdk.dev/docs/adapters/scaleway): Scaleway Object Storage via the S3-compatible API. Endpoint derived from the region code (fr-par, nl-ams, pl-waw).
- [SharePoint](https://files-sdk.dev/docs/adapters/sharepoint): SharePoint document libraries via Microsoft Graph. Resolves siteUrl and library names; delegates to the OneDrive adapter for the file operations.
- [Storj](https://files-sdk.dev/docs/adapters/storj): Storj DCS via the S3-compatible Gateway. Defaults to the hosted Gateway MT with path-style addressing, keys auto-loaded from STORJ_* env vars.
- [Supabase Storage](https://files-sdk.dev/docs/adapters/supabase): Supabase Storage via @supabase/storage-js. Pass an existing SupabaseClient to share auth/postgrest with the rest of your app.
- [Tencent Cloud Object Storage](https://files-sdk.dev/docs/adapters/tencent): Tencent Cloud Object Storage (COS) via the S3-compatible API. Endpoint derived from the region code; bucket name must include the -<appid> suffix.
- [Tigris](https://files-sdk.dev/docs/adapters/tigris): Tigris globally-distributed object storage via the S3-compatible API. Fixed global endpoint, region defaults to auto.
- [UploadThing](https://files-sdk.dev/docs/adapters/uploadthing): UploadThing via the uploadthing/server SDK. Auto-loads UPLOADTHING_TOKEN and maps your keys onto UploadThing's customId so operations route by your key.
- [Vercel Blob](https://files-sdk.dev/docs/adapters/vercel-blob): Store files in Vercel Blob with files-sdk, using OIDC on Vercel (BLOB_STORE_ID, no secret) or a BLOB_READ_WRITE_TOKEN anywhere, public or private.
- [Vultr Object Storage](https://files-sdk.dev/docs/adapters/vultr): Vultr Object Storage via the S3-compatible API. Endpoint derived from the cluster code (ewr1, sjc1, ams1, blr1, ...).
- [Wasabi](https://files-sdk.dev/docs/adapters/wasabi): Wasabi Hot Cloud Storage via its S3-compatible API - a thin wrapper around the S3 adapter with AWS-style region names mapped to Wasabi's own endpoints.
- [Yandex Object Storage](https://files-sdk.dev/docs/adapters/yandex): Yandex Object Storage via the S3-compatible API. Fixed global endpoint, region defaults to ru-central1, keys auto-loaded from YANDEX_* env vars.

### AI

- [Claude Agent SDK](https://files-sdk.dev/docs/ai/claude): Expose a configured Files instance to the Claude Agent SDK as an in-process MCP server with allowedTools and canUseTool wired up.
- [OpenAI](https://files-sdk.dev/docs

Canonical: https://files-sdk.dev/.well-known/security.txt
Contact: https://github.com/haydenbleasel/files-sdk/security/advisories/new
Expires: 2027-09-16T00:00:00Z
Preferred-Languages: en