Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Introduction

Files SDK is a unified storage API for 40+ providers - one class, eleven methods, a typed escape hatch, and an agent-friendly CLI.

What is Files SDK?

A single TypeScript API for object storage that works the same way across AWS S3, Cloudflare R2, Vercel Blob, Google Cloud Storage, Azure, Supabase, Netlify Blobs, the S3-compatible long tail (MinIO, RustFS, Backblaze, Wasabi, DigitalOcean Spaces, Scaleway, OVH, Hetzner, Tigris, Storj, Filebase, Akamai, IDrive, Vultr, IBM COS, Oracle, Exoscale, Alibaba, Tencent, Yandex, Archil, Neon), the consumer-style providers (Dropbox, Box, Google Drive, OneDrive, SharePoint), the upload and media services (UploadThing, Cloudinary, Bunny Storage), the BaaS stack (Appwrite, PocketBase, Firebase Storage, Convex), file servers over FTP, SFTP, and WebDAV, Bun’s native S3 client, and local fs and in-memory adapters for tests. The provider catalog has the full list.

Eleven methods cover the surface area you actually use: upload, download, head, exists (each taking one key or an array for bulk), delete (one key or an array for bulk), copy, move, list (or listAll to walk every page), search, url, signedUploadUrl. When you need provider-specific power - S3 versioning, lifecycle rules, multipart, ACLs - drop down to the native client via files.raw, which stays typed per adapter.

Why Files SDK?

Every storage SDK ships with its own shape: PutObjectCommand, put(), uploadStream, createWriteStream, presigner factories, ACL nouns, error envelopes. Switching providers - or supporting more than one - means rewriting the call sites and re-learning the error model.

Files SDK collapses that into one class and one error type:

  • One API - same call shape across every adapter. The code that uploads to S3 is the code that uploads to Vercel Blob.
  • Normalized errors - FilesError with a small enum of codes (NotFound, Unauthorized, Conflict, ReadOnly, Provider), with the original error preserved on cause.
  • Per-adapter subpaths - adapters are subpath exports (files-sdk/s3, files-sdk/r2, …). The provider SDK you don’t import isn’t bundled.
  • Typed escape hatch - files.raw is typed as the underlying client (S3Client, R2Bucket, VercelBlobClient, …), so the unified API never traps you.
  • Agent-friendly CLI - one files binary, JSON output, stdin/stdout streaming, plus a built-in MCP server. Same semantics as the SDK.

Next steps

  • Installation - install the SDK and the adapter peer dependencies.
  • Usage - construct a Files instance and run the core methods.
  • API reference - the full method surface, options, and the StoredFile type.
  • Adapters - per-provider setup, options, and gotchas.
  • CLI - the same API as an agent-friendly files binary with JSON output and an MCP server.
  • UI - React, Vue, and Svelte bindings backed by a server gateway.
  • Plugins - encryption, compression, validation, versioning, and more as an ordered pipeline.
  • AI integrations - hand your bucket to OpenAI, Claude, or the Vercel AI SDK as ready-made tools.
  • FAQ - common questions, answered.
  • Changelog - what shipped in each release.

Was this page helpful?