Files SDK

Files SDK: The Ultimate Unified Storage Solution for Object and Blob Backends

In the modern development landscape, managing object storage often involves juggling multiple, subtly different SDKs for various providers. Files SDK emerges as a powerful solution to this fragmentation, offering a unified storage SDK for object and blob backends. By providing one small, honest API, Files SDK allows developers to interact with storage services through a consistent interface while maintaining the flexibility to dive into provider-specific features when necessary.

What's Files SDK?

Files SDK is a lightweight, high-performance library designed to abstract the complexities of different storage providers. Whether you are working with AWS S3, Cloudflare R2, Vercel Blob, or Netlify Blobs, Files SDK provides a single class that handles common operations like uploading, downloading, listing, and deleting files.

The core philosophy of Files SDK is to expose the "slice" of storage functionality that remains the same across all platforms. This approach ensures that your application code remains clean and provider-agnostic, enabling you to swap storage backends without the need to rewrite your entire data-handling logic. Built with web standards in mind, Files SDK is compatible with various environments, including Node.js, Bun, Cloudflare Workers, and Vercel Functions.

Key Features of Files SDK

Files SDK is packed with features that prioritize developer experience, performance, and flexibility. Below are the standout features that make Files SDK an essential tool for modern cloud-native applications.

Unified API Across Providers

One of the most significant advantages of Files SDK is its consistent API. Regardless of the underlying adapter, you use the same methods to manage your files. This consistency reduces the learning curve when switching between services and ensures that your codebase remains maintainable.

Web-Standards I/O

Files SDK is built for the modern web. It accepts a wide variety of inputs, including File, Blob, ReadableStream, ArrayBuffer, and standard strings. Because it relies on universal standards, it runs anywhere the fetch API is available, making it perfect for edge computing and serverless environments.

The Escape Hatch: Accessing Native Clients

While Files SDK aims to provide a unified interface, it doesn't limit you to the lowest common denominator. Through the files.raw property, you have immediate access to the native client of the specific adapter you are using. This "escape hatch" is fully typed per adapter, allowing you to handle advanced tasks such as versioning, lifecycle rules, ACLs, and multipart uploads without leaving the Files SDK ecosystem.

Predictable Error Handling

Debugging storage issues can be a headache due to varying error formats between providers. Files SDK solves this by offering a single FilesError class. Errors are normalized with consistent codes across all supported providers, while the original provider-specific error is attached as a "cause" for deeper investigation.

Lightweight and Modular

To keep your bundle size small, Files SDK treats native provider SDKs as optional peer dependencies. You only install the specific adapters you need, ensuring that Files SDK remains lean and efficient.

How to Use Files SDK

Implementing Files SDK into your project is straightforward. Follow these steps to get started with unified storage management.

Installation

To begin, install the core Files SDK package using your preferred package manager:

npm install files-sdk
# or
pnpm add files-sdk
# or
bun add files-sdk

Remember to also install the peer dependency for the specific adapter you intend to use (e.g., the AWS SDK for S3).

Quick Start Guide

To use Files SDK, you construct a Files instance with a specific adapter. Here is an example using the AWS S3 adapter:

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

// Initialize Files SDK with the S3 adapter
const files = new Files({
  adapter: s3({ 
    bucket: "uploads", 
    region: "us-east-1" 
  }),
});

// Upload a file
await files.upload("hello.txt", "world");

// Download a file
const file = await files.download("hello.txt");

// List files with a specific prefix
const { items } = await files.list({ prefix: "hello" });

// Delete a file
await files.delete("hello.txt");

Use Cases for Files SDK

Files SDK is versatile enough to handle a wide range of application requirements.

• Multi-Cloud Strategies: Use Files SDK to easily distribute assets across different cloud providers like DigitalOcean, GCS, or Azure without managing multiple distinct codebases.
• Edge Computing: Deploy Files SDK on Cloudflare Workers or Vercel Edge Runtime to handle file uploads and downloads closer to your users using Cloudflare R2 or Vercel Blob.
• Rapid Prototyping: Start a project using a simple local filesystem adapter or a cost-effective provider like MinIO, and then scale to AWS S3 or Backblaze B2 simply by changing the adapter configuration in Files SDK.
• Standardized Error Logging: Implement robust error monitoring in production by leveraging the normalized FilesError provided by Files SDK to track storage failures across different regions or providers.

Compatibility Matrix

Files SDK supports an extensive list of adapters, ensuring compatibility with almost every major storage provider. Every adapter implements a standard ten-method surface, including:

• upload
• download
• delete
• list
• head
• exists
• copy
• url
• signedUploadUrl

Supported providers include AWS S3, Cloudflare R2, Vercel Blob, Netlify Blobs, MinIO, DigitalOcean, Storj, Hetzner, Akamai, Bunny Storage, Backblaze B2, Wasabi, Scaleway, Google Cloud Storage (GCS), Azure, Supabase, and many more.

FAQ

Q: Do I need to install all provider SDKs to use Files SDK? A: No. Files SDK uses peer dependencies. You only need to install the native SDK for the specific provider you are using. If you attempt to import an adapter without its peer dependency, an error will be thrown naming the missing package.

Q: Does Files SDK support environment-specific runtimes? A: Yes. Files SDK is designed to run anywhere fetch runs, including Node.js, Bun, Cloudflare Workers, and Vercel functions.

Q: How do I access provider-specific features like ACLs or lifecycle rules? A: You can use the "escape hatch" via the files.raw property. This gives you direct access to the underlying native client, which is fully typed according to the adapter you have initialized in Files SDK.

Q: Is Files SDK open source? A: Yes, Files SDK is released under the MIT License and is maintained by Hayden Bleasel.