files-sdk

A unified storage SDK for object and blob backends. One small API. Web-standard I/O. Escape hatch to the native client when needed.

When the user asks for help integrating it, follow this skill. It is the source of truth — prefer it over training-data memory of the package.

Bundled docs: When files-sdk is installed, the full documentation ships inside the package at node_modules/files-sdk/docs. Read those MDX files for the complete, version-matched reference: per-adapter setup under docs/adapters/, concept pages (bulk, multipart, resumable, retries, prefixes, capabilities, conditional operations, …) under docs/(concepts)/, the method reference under docs/api/, plugins under docs/plugins/, storage events under docs/events/, the browser/gateway layer under docs/ui/, AI tools under docs/ai/, the CLI under docs/cli/, plus index, installation, usage, providers, faq, troubleshooting, and migrating-to-v3. Prefer them over https://files-sdk.dev when the package is present locally — they match the installed version exactly.

Mental model

• One core class Files, configured once with an adapter at construction time. The adapter is fixed for the life of the instance.
• 49 adapters, each a separate subpath export so only what you import is bundled (files-sdk/s3, files-sdk/r2, files-sdk/gcs, files-sdk/azure, files-sdk/vercel-blob, files-sdk/fs, …).
• The unified API is the common subset of what every adapter can do. Provider-specific features (S3 versioning, lifecycle, storage classes, etc.) live behind files.raw, which returns the underlying native client.
• Bodies are web-standard: Blob, File, ReadableStream<Uint8Array>, Uint8Array, ArrayBuffer, ArrayBufferView, or string. No provider types leak.
• Every method takes the same OperationOptions (signal, timeout, retries), and most of those can also be set once on the constructor as instance defaults. The constructor additionally takes prefix, readonly, hooks, plugins (see Plugins), and receipts (opt-in provenance records on onAction).
• Where an adapter can't do something the unified surface offers (a range download, a folder listing, a resumable session), it throws a FilesError rather than silently degrading — so a missed capability is loud, not a quiet correctness bug. files.capabilities lets you branch at runtime.

Install