Files SDK

https://files-sdk.dev
Admin
A unified SDK for cloud storage providing a single API across S3, R2, GCS, Azure, Vercel Blob, and...
Tokens:103,907
Snippets:1,236
Trust Score:4.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Files SDK

Source: https://files-sdk.dev/

Install the SDK using your preferred package manager. Ensure you also install the native SDK for each adapter used as a peer dependency.

```bash
npm install files-sdk
```

```bash
pnpm add files-sdk
```

```bash
bun add files-sdk
```

```bash
yarn add files-sdk
```

--------------------------------

### Install UploadThing Adapter

Source: https://files-sdk.dev/docs/adapters/uploadthing

Install the adapter as a peer dependency alongside the files-sdk.

```bash
files-sdk uploadthing
```

--------------------------------

### Install PocketBase Adapter

Source: https://files-sdk.dev/docs/adapters/pocketbase

Install the adapter as a peer dependency alongside the files-sdk.

```bash
files-sdk pocketbase
```

--------------------------------

### Install all prebuilt components

Source: https://files-sdk.dev/docs/ui

Use this command to install the complete bundle of SDK-wired UI components.

```jsx
<ComponentInstall name="all" />
```

--------------------------------

### Install dependencies

Source: https://files-sdk.dev/docs/adapters/akamai

Install the SDK and required peer dependencies for the Akamai adapter.

```bash
files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

--------------------------------

### Install Dropbox Adapter

Source: https://files-sdk.dev/docs/adapters/dropbox

Install the adapter as a peer dependency alongside the main SDK.

```bash
files-sdk dropbox
```

--------------------------------

### Install SFTP adapter dependencies

Source: https://files-sdk.dev/docs/adapters/sftp

Install the required peer dependency alongside the SDK.

```bash
files-sdk ssh2-sftp-client
```

--------------------------------

### Install FTP adapter dependency

Source: https://files-sdk.dev/docs/adapters/ftp

Install the basic-ftp peer dependency alongside the SDK.

```bash
files-sdk basic-ftp
```

--------------------------------

### Install Bunny Storage Adapter

Source: https://files-sdk.dev/docs/adapters/bunny-storage

Install the required peer dependency alongside the main SDK.

```bash
files-sdk @bunny.net/storage-sdk
```

--------------------------------

### Install WebDAV adapter

Source: https://files-sdk.dev/docs/adapters/webdav

Install the webdav peer dependency alongside the files-sdk.

```bash
files-sdk webdav
```

--------------------------------

### Install Files SDK

Source: https://files-sdk.dev/docs/adapters/bun-s3

Command to install the Files SDK package.

```bash
files-sdk
```

--------------------------------

### Install Box SDK Adapter

Source: https://files-sdk.dev/docs/adapters/box

Install the required peer dependency alongside the main SDK.

```bash
files-sdk box-typescript-sdk-gen
```

--------------------------------

### Install Convex Adapter

Source: https://files-sdk.dev/docs/adapters/convex

Install the necessary package for the Convex adapter.

```bash
files-sdk convex
```

--------------------------------

### Install Vercel Blob adapter

Source: https://files-sdk.dev/docs/adapters/vercel-blob

Install the adapter as a peer dependency alongside the main SDK.

```bash
files-sdk @vercel/blob
```

--------------------------------

### Install files-sdk

Source: https://files-sdk.dev/docs/installation

Install the core files-sdk package via npm.

```bash
npm install files-sdk
```

--------------------------------

### Install Supabase Storage dependencies

Source: https://files-sdk.dev/docs/adapters/supabase

Install the SDK and the required peer dependency.

```bash
files-sdk @supabase/storage-js
```

--------------------------------

### Initialize Bun S3 Adapter

Source: https://files-sdk.dev/docs/adapters/bun-s3

Configuration examples for initializing the Files SDK with the Bun S3 adapter, either by providing bucket credentials or a pre-configured Bun S3 client.

```ts
import { Files } from "files-sdk";
import { bunS3 } from "files-sdk/bun-s3";

const files = new Files({
  adapter: bunS3({
    bucket: "uploads",
    region: "us-east-1",
    // accessKeyId / secretAccessKey auto-loaded by Bun from
    // S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY (or AWS_* equivalents)
  }),
});

// Or hand it the singleton Bun.s3 client directly:
new Files({ adapter: bunS3({ client: Bun.s3 }) });
```

--------------------------------

### Install dependencies

Source: https://files-sdk.dev/docs/ai/vercel

Install the required peer dependencies for the AI SDK integration.

```bash
ai zod
```

--------------------------------

### R2 Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/r2

Example of initializing the Files client with the R2 adapter using the fetch client configuration.

```APIDOC
## R2 Adapter Initialization

### Description
Initializes the Files client using the R2 adapter with the fetch client, suitable for edge environments like Cloudflare Workers.

### Configuration
- **adapter**: r2() - The adapter instance
- **bucket**: string - The name of the R2 bucket
- **accountId**: string - The R2 account ID
- **client**: "fetch" - Specifies the use of the lightweight fetch engine

### Example
```ts
const files = new Files({
  adapter: r2({
    bucket: "uploads",
    accountId: process.env.R2_ACCOUNT_ID!,
    client: "fetch",
  }),
});
```
```

--------------------------------

### Install SharePoint adapter dependencies

Source: https://files-sdk.dev/docs/adapters/sharepoint

Install the SDK along with the required peer dependencies for authentication and Graph API interaction.

```bash
files-sdk @azure/identity @microsoft/microsoft-graph-client
```

--------------------------------

### Upload Progress Component Example

Source: https://files-sdk.dev/docs/ui/components/upload-progress

Demonstrates a full implementation with file selection and automatic upload triggering on mount.

```tsx
"use client";

import { UploadIcon } from "lucide-react";
import type { ChangeEvent } from "react";
import { useEffect, useRef } from "react";

import { Button } from "@/components/ui/button";
import { demoFiles } from "@/lib/demo-files";
import { UploadProgress } from "@/registry/files-sdk/upload-progress/upload-progress";

const Example = () => {
  const files = demoFiles;
  const inputRef = useRef<HTMLInputElement>(null);

  // Read `files` via a ref so this one-shot effect never re-runs on store
  // changes (see the file-list/file-preview note on the loop footgun).
  const filesRef = useRef(files);
  filesRef.current = files;

  // Kick off a sample upload on mount so the progress UI starts populated.
  useEffect(() => {
    const bytes = new Uint8Array(3 * 1024 * 1024);
    const sample = new File([bytes], "vacation-photo.jpg", {
      type: "image/jpeg",
    });
    void filesRef.current.upload(sample);
  }, []);

  const handleChange = async (event: ChangeEvent<HTMLInputElement>) => {
    // Capture the element now — React nulls `currentTarget` after the handler's
    // synchronous phase, so it's gone by the time the uploads below resolve.
    const input = event.currentTarget;
    const picked = input.files;
    if (!picked?.length) {
      return;
    }
    for (const file of picked) {
      // eslint-disable-next-line no-await-in-loop -- demo uploads files one at a time so progress reads cleanly
      await files.upload(`demo/${file.name}`, file, {
        contentType: file.type,
      });
    }
    input.value = "";
  };

  return (
    <div className="flex flex-col gap-4">
      <div>
        <Button
          onClick={() => inputRef.current?.click()}
          type="button"
          variant="outline"
        >
          <UploadIcon />
          Choose files
        </Button>
        <input
          aria-label="Choose files to upload"
          className="hidden"
          multiple
          onChange={(event) => void handleChange(event)}
          ref={inputRef}
          type="file"
        />
      </div>
      <UploadProgress files={files} />
    </div>
  );
};

export default Example;
```

--------------------------------

### Install Google Drive adapter dependencies

Source: https://files-sdk.dev/docs/adapters/google-drive

Install the required peer dependencies alongside the SDK to ensure the adapter functions correctly.

```bash
files-sdk @googleapis/drive google-auth-library
```

--------------------------------

### Install Appwrite adapter dependencies

Source: https://files-sdk.dev/docs/adapters/appwrite

Install the files-sdk and the optional node-appwrite peer dependency.

```bash
files-sdk node-appwrite
```

--------------------------------

### Install GCS adapter dependencies

Source: https://files-sdk.dev/docs/adapters/gcs

Install the required peer dependency alongside the SDK.

```bash
files-sdk @google-cloud/storage
```

--------------------------------

### Install Firebase Storage Adapter

Source: https://files-sdk.dev/docs/adapters/firebase-storage

Install the required peer dependency alongside the SDK to ensure runtime resolution.

```bash
files-sdk firebase-admin
```

--------------------------------

### Install the CLI globally

Source: https://files-sdk.dev/docs/cli

Installs the files-sdk package globally to make the files binary available on your system PATH.

```bash
npm install -g files-sdk
```

--------------------------------

### Install Netlify Blobs dependency

Source: https://files-sdk.dev/docs/adapters/netlify-blobs

Install the required peer dependency alongside the Files SDK.

```bash
files-sdk @netlify/blobs
```

--------------------------------

### Install Azure Blob Storage dependencies

Source: https://files-sdk.dev/docs/adapters/azure

Install the SDK and the required peer dependency to enable Azure adapter functionality.

```bash
files-sdk @azure/storage-blob
```

--------------------------------

### Install Cloudinary Adapter

Source: https://files-sdk.dev/docs/adapters/cloudinary

Install the cloudinary package alongside the files-sdk to ensure adapter imports resolve correctly.

```bash
files-sdk cloudinary
```

--------------------------------

### Install Provider SDKs

Source: https://files-sdk.dev/changelog/files-sdk-1-4-0

Install the necessary peer dependencies for specific storage providers after upgrading to version 1.4.0.

```sh
# S3 (and any S3-compatible: R2, MinIO, DigitalOcean Spaces, …)
npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

# GCS
npm install files-sdk @google-cloud/storage google-auth-library

# Azure
npm install files-sdk @azure/storage-blob @azure/identity
```

--------------------------------

### Install S3 adapter dependencies

Source: https://files-sdk.dev/docs/adapters

Install the Files SDK along with the required AWS SDK peer dependencies for S3 support.

```bash
npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

```bash
pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

```bash
yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

```bash
bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

--------------------------------

### Initialize Files Client with Configuration

Source: https://files-sdk.dev/docs/usage

Configure the client with an adapter, key prefixing, and global timeout and retry settings.

```ts
const files = new Files({
  adapter: s3({ bucket: "uploads" }),
  prefix: "users", // every key resolves under users/
  timeout: 10_000, // default per-attempt timeout
  retries: 3, // retry provider failures
});
```

--------------------------------

### MinIO Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/minio

How to initialize the Files SDK with the MinIO adapter.

```APIDOC
## MinIO Adapter Initialization

### Description
Initialize the Files SDK using the MinIO adapter to connect to a self-hosted S3-compatible server.

### Usage
```ts
import { Files } from "files-sdk";
import { minio } from "files-sdk/minio";

const files = new Files({
  adapter: minio({
    bucket: "uploads",
    endpoint: "http://localhost:9000",
  }),
});
```
```

--------------------------------

### Configure Files with a custom plugin

Source: https://files-sdk.dev/changelog/files-sdk-1-8-0

Demonstrates how to initialize the Files client with the new plugin system using an ordered onion architecture.

```ts
const files = createFiles({
  adapter: s3({ bucket: "uploads" }),
  plugins: [
    {
      name: "uppercase",
      wrap: handlers({
        upload: (op, next) =>
          next({ ...op, body: (op.body as string).toUpperCase() }),
      }),
    },
  ],
});
```

--------------------------------

### Install OpenAI Responses dependencies

Source: https://files-sdk.dev/docs/ai/openai

Install the required peer dependencies for the Responses API integration.

```bash
openai zod
```

--------------------------------

### Hetzner Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/hetzner

How to initialize the Files SDK with the Hetzner adapter.

```APIDOC
## Initialization

### Description
Initialize the Files SDK using the Hetzner adapter. The adapter requires a bucket name and a region (fsn1, nbg1, or hel1). Credentials are automatically loaded from HCLOUD_ACCESS_KEY_ID and HCLOUD_SECRET_ACCESS_KEY environment variables.

### Usage
```ts
import { Files } from "files-sdk";
import { hetzner } from "files-sdk/hetzner";

const files = new Files({
  adapter: hetzner({
    bucket: "uploads",
    region: "fsn1"
  }),
});
```
```

--------------------------------

### alibaba()

Source: https://files-sdk.dev/docs/adapters/alibaba

Initializes the Alibaba Cloud OSS adapter for use with the Files SDK. It requires a bucket name and region, while credentials are automatically loaded from environment variables.

```APIDOC
## alibaba(options)

### Description
Creates an instance of the Alibaba Cloud OSS adapter to be used within the Files SDK configuration.

### Parameters
- **bucket** (string) - Required - The name of the Alibaba Cloud OSS bucket.
- **region** (string) - Required - The Alibaba Cloud region code (e.g., "cn-hangzhou", "ap-southeast-1").

### Usage Example
```ts
import { Files } from "files-sdk";
import { alibaba } from "files-sdk/alibaba";

const files = new Files({
  adapter: alibaba({
    bucket: "uploads",
    region: "cn-hangzhou"
  }),
});
```
```

--------------------------------

### Initialize Alibaba adapter

Source: https://files-sdk.dev/docs/adapters/alibaba

Configure the Files SDK with the Alibaba adapter, providing the bucket name and region. Credentials are automatically loaded from ALIBABA_ACCESS_KEY_ID and ALIBABA_ACCESS_KEY_SECRET environment variables.

```ts
import { Files } from "files-sdk";
import { alibaba } from "files-sdk/alibaba";

const files = new Files({
  adapter: alibaba({
    bucket: "uploads",
    region: "cn-hangzhou", // or "cn-shanghai", "ap-southeast-1", ...
    // accessKeyId / secretAccessKey auto-loaded from
    // ALIBABA_ACCESS_KEY_ID / ALIBABA_ACCESS_KEY_SECRET
  }),
});
```

--------------------------------

### Install OpenTelemetry API Dependency

Source: https://files-sdk.dev/docs/plugins/tracing

Install the optional peer dependency required for the tracing plugin to function.

```bash
npm install @opentelemetry/api
```

--------------------------------

### Initialize Filesystem Adapter

Source: https://files-sdk.dev/docs/adapters/fs

Configure the Files instance with the fs adapter pointing to a local directory. Use the optional urlBaseUrl to map file paths to a local development server URL.

```typescript
import { Files } from "files-sdk";
import { fs } from "files-sdk/fs";

// Writes objects under `./.uploads` with a sidecar `.meta.json`
// per file for Content-Type, ETag, and user metadata. Designed for
// dev and CI - same Adapter contract as the cloud adapters, so swap
// it in via env without changing call sites.
const files = new Files({
  adapter: fs({
    root: "./.uploads",
    // Optional: configure if a dev server exposes the same root over
    // HTTP, so url() returns a browser-friendly URL instead of file://.
    // urlBaseUrl: "http://localhost:3000/files",
  }),
});
```

--------------------------------

### Install OpenAI Agents SDK dependencies

Source: https://files-sdk.dev/docs/ai/openai

Install the required peer dependencies for the Agents SDK integration.

```bash
@openai/agents zod
```

--------------------------------

### SFTP Adapter Configuration

Source: https://files-sdk.dev/docs/adapters/sftp

How to initialize the Files SDK with the SFTP adapter using authentication credentials and a root directory.

```APIDOC
## SFTP Adapter Initialization

### Description
Initializes the Files SDK with the SFTP adapter. The adapter maps virtual keys to paths under a specified root directory on the remote server.

### Configuration Options
- **host** (string) - Required - The SFTP server hostname.
- **username** (string) - Required - The username for authentication.
- **privateKey** (string) - Optional - The private key for authentication (takes precedence over password).
- **root** (string) - Optional - The base directory on the remote server for virtual keys.

### Example
```ts
import { Files } from "files-sdk";
import { sftp } from "files-sdk/sftp";

const files = new Files({
  adapter: sftp({
    host: "files.example.com",
    username: process.env.SFTP_USERNAME!,
    privateKey: process.env.SFTP_PRIVATE_KEY!,
    root: "/uploads",
  }),
});
```
```

--------------------------------

### Install Claude Agent SDK dependencies

Source: https://files-sdk.dev/docs/ai/claude

Install the required peer dependencies for the Claude Agent SDK integration.

```bash
@anthropic-ai/claude-agent-sdk zod
```

--------------------------------

### Initialize WebDAV adapter

Source: https://files-sdk.dev/docs/adapters/webdav

Configure the adapter with base URL and credentials. Virtual keys are mapped to a root directory on the server.

```typescript
import { Files } from "files-sdk";
import { webdav } from "files-sdk/webdav";

const files = new Files({
  adapter: webdav({
    baseUrl: "https://cloud.example.com/remote.php/dav/files/alice",
    username: process.env.WEBDAV_USERNAME!,
    password: process.env.WEBDAV_PASSWORD!,
    // authType: "digest", // "basic" (default) | "digest" | "token" | "none"
    root: "/uploads", // virtual keys resolve under here; defaults to "/"
  }),
});

await files.upload("reports/q1.csv", csv, { contentType: "text/csv" });
const file = await files.download("reports/q1.csv");
```

--------------------------------

### Initialize MinIO adapter

Source: https://files-sdk.dev/docs/adapters/minio

Configure the Files SDK with the MinIO adapter, providing the bucket name and endpoint. Credentials are automatically loaded from environment variables.

```ts
import { Files } from "files-sdk";
import { minio } from "files-sdk/minio";

const files = new Files({
  adapter: minio({
    bucket: "uploads",
    endpoint: "http://localhost:9000",
    // accessKeyId / secretAccessKey auto-loaded from
    // MINIO_ACCESS_KEY_ID / MINIO_SECRET_ACCESS_KEY
  }),
});
```

--------------------------------

### Filebase Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/filebase

How to initialize the Files SDK with the Filebase adapter.

```APIDOC
## Initialization

### Description
Initialize the Files SDK using the Filebase adapter. The adapter automatically loads credentials from `FILEBASE_ACCESS_KEY_ID` and `FILEBASE_SECRET_ACCESS_KEY` environment variables.

### Usage
```ts
import { Files } from "files-sdk";
import { filebase } from "files-sdk/filebase";

const files = new Files({
  adapter: filebase({
    bucket: "uploads",
  }),
});
```
```

--------------------------------

### Swap storage adapters

Source: https://files-sdk.dev/docs/usage

Demonstrates switching the backend by providing a different adapter to the Files constructor.

```ts
import { r2 } from "files-sdk/r2";
import { vercelBlob } from "files-sdk/vercel-blob";

const files = new Files({ adapter: r2({ accountId, bucket: "uploads" }) });
// or
const files = new Files({
  adapter: vercelBlob({ token: process.env.BLOB_READ_WRITE_TOKEN! }),
});
```

--------------------------------

### Initialize Backblaze B2 adapter

Source: https://files-sdk.dev/docs/adapters/backblaze-b2

Configure the Files SDK with the Backblaze B2 adapter, providing the bucket name and region. Credentials are automatically loaded from environment variables.

```ts
import { Files } from "files-sdk";
import { backblazeB2 } from "files-sdk/backblaze-b2";

const files = new Files({
  adapter: backblazeB2({
    bucket: "uploads",
    region: "us-west-002", // or "us-east-005", "eu-central-003", ...
    // accessKeyId / secretAccessKey auto-loaded from
    // B2_APPLICATION_KEY_ID / B2_APPLICATION_KEY
  }),
});
```

--------------------------------

### sharepoint(options)

Source: https://files-sdk.dev/docs/adapters/sharepoint

Initializes the SharePoint adapter for use with the Files SDK.

```APIDOC
## sharepoint(options)

### Description
Initializes the SharePoint adapter. This adapter resolves the site URL and document library name to a drive ID, then delegates file operations to the OneDrive adapter.

### Parameters
- **siteUrl** (string) - Required - The URL of the SharePoint site.
- **documentLibrary** (string) - Optional - The name of the document library. If omitted, the default library is used.
- **clientCredentials** (object) - Required - Authentication credentials including tenantId, clientId, and clientSecret.
- **rootFolderPath** (string) - Optional - The root folder path within the library.
```

--------------------------------

### url

Source: https://files-sdk.dev/docs/cli/commands

Gets a read URL for a key.

```APIDOC
## url

### Description
Get a read URL for a key — presigned and short-lived on signing adapters, a public URL for CDN-backed providers. `--expires-in` sets the lifetime in seconds.

### Usage
`files --provider <provider> --bucket <bucket> url <key> --expires-in <seconds>`
```

--------------------------------

### Handling FilesError

Source: https://files-sdk.dev/docs/api/errors

Example of catching and handling a specific FilesError code.

```APIDOC
## Handling FilesError

### Description
All single-key methods throw a `FilesError` on failure. You can use the `code` property to handle specific error scenarios like missing files.

### Example
```ts
import { FilesError } from "files-sdk";

try {
  await files.download("missing.png");
} catch (err) {
  if (err instanceof FilesError && err.code === "NotFound") {
    // handle gracefully
    return null;
  }
  throw err;
}
```
```

--------------------------------

### Initialize and use the FTP adapter

Source: https://files-sdk.dev/docs/adapters/ftp

Configure the Files client with the FTP adapter and perform basic file operations. Ensure the environment variables for authentication are set.

```typescript
import { Files } from "files-sdk";
import { ftp } from "files-sdk/ftp";

const files = new Files({
  adapter: ftp({
    host: "ftp.example.com",
    user: process.env.FTP_USERNAME!,
    password: process.env.FTP_PASSWORD!,
    secure: true, // FTPS over explicit TLS — strongly recommended
    root: "/uploads", // virtual keys resolve under here; defaults to "."
  }),
});

await files.upload("reports/q1.csv", csv, { contentType: "text/csv" });
const file = await files.download("reports/q1.csv");
```

--------------------------------

### Configure FilesModule Asynchronously

Source: https://files-sdk.dev/docs/ui/server/nestjs

Uses forRootAsync to inject configuration services for dynamic module setup.

```typescript
import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { createFiles } from "files-sdk";
import { FilesModule } from "files-sdk/nestjs";
import { s3 } from "files-sdk/s3";

@Module({
  imports: [
    ConfigModule.forRoot(),
    FilesModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        files: createFiles({
          adapter: s3({ bucket: config.getOrThrow("S3_BUCKET") }),
        }),
        secret: config.getOrThrow("FILES_API_SECRET"),
        allowedOrigins: [config.getOrThrow("APP_ORIGIN")],
        operations: ["upload", "download", "list", "delete", "url"],
      }),
    }),
  ],
})
export class AppModule {}
```

--------------------------------

### Scaleway Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/scaleway

How to initialize the Files SDK with the Scaleway adapter.

```APIDOC
## Initialization

### Description
Initialize the Files SDK using the Scaleway adapter. The adapter automatically loads credentials from `SCW_ACCESS_KEY` and `SCW_SECRET_KEY` environment variables.

### Usage
```ts
import { Files } from "files-sdk";
import { scaleway } from "files-sdk/scaleway";

const files = new Files({
  adapter: scaleway({
    bucket: "uploads",
    region: "fr-par", // Supported: "fr-par", "nl-ams", "pl-waw"
  }),
});
```
```

--------------------------------

### Akamai Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/akamai

How to initialize the Files SDK with the Akamai adapter.

```APIDOC
## Akamai Adapter Initialization

### Description
Initialize the Files SDK using the Akamai adapter to connect to Akamai Cloud Object Storage.

### Usage
```ts
import { Files } from "files-sdk";
import { akamai } from "files-sdk/akamai";

const files = new Files({
  adapter: akamai({
    bucket: "uploads",
    region: "us-iad-1"
  }),
});
```

### Configuration
- **bucket** (string) - Required - The name of the storage bucket.
- **region** (string) - Required - The region or cluster code (e.g., "us-iad-1", "nl-ams-1").
- **Environment Variables** - The adapter automatically loads `AKAMAI_ACCESS_KEY_ID` and `AKAMAI_SECRET_ACCESS_KEY` from the environment.
```

--------------------------------

### ShareDialog with useFiles Hook

Source: https://files-sdk.dev/docs/ui/components/share-dialog

Usage example integrating the ShareDialog with the useFiles hook for dynamic file management.

```tsx
import { useFiles } from "files-sdk/react";

import { ShareDialog } from "@/components/files-sdk/share-dialog";

export function Row({ fileKey }: { fileKey: string }) {
  const files = useFiles({ endpoint: "/api/files" });

  return <ShareDialog files={files} fileKey={fileKey} />;
}
```

--------------------------------

### Initialize Wasabi adapter

Source: https://files-sdk.dev/docs/adapters/wasabi

Configure the Files SDK with the Wasabi adapter, providing the bucket name and region. Credentials are automatically loaded from environment variables.

```ts
import { Files } from "files-sdk";
import { wasabi } from "files-sdk/wasabi";

const files = new Files({
  adapter: wasabi({
    bucket: "uploads",
    region: "us-east-1", // or "eu-central-1", "ap-northeast-1", ...
    // accessKeyId / secretAccessKey auto-loaded from
    // WASABI_ACCESS_KEY_ID / WASABI_SECRET_ACCESS_KEY
  }),
});
```

--------------------------------

### Execute a one-shot command

Source: https://files-sdk.dev/docs/cli

Runs a command without requiring a global installation by using npx to fetch the package on demand.

```bash
npx -p files-sdk files --provider fs --root ./uploads list
```

--------------------------------

### S3 Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/s3

How to initialize the Files SDK with the S3 adapter.

```APIDOC
## S3 Adapter Initialization

### Description
Initialize the Files SDK instance using the S3 adapter to connect to an S3 bucket.

### Usage
```ts
import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = new Files({
  adapter: s3({
    bucket: "uploads",
    region: "us-east-1",
  }),
});
```
```

--------------------------------

### Mounting Files Router in Next.js

Source: https://files-sdk.dev/docs/ui/server/gateway

Example of setting up a Files API route handler in a Next.js application using the createRouteHandler adapter.

```typescript
import { createFiles } from "files-sdk";
import { s3 } from "files-sdk/s3";
import { createFilesRouter } from "files-sdk/api";
import { createRouteHandler } from "files-sdk/next";

const router = createFilesRouter({
  files: createFiles({ adapter: s3({ bucket: "uploads" }) }),
  authorize: async ({ req }) => {
    /* … */
  },
});

export const { GET, POST, PUT } = createRouteHandler(router);
```

--------------------------------

### Initialize iDrive e2 adapter

Source: https://files-sdk.dev/docs/adapters/idrive-e2

Configure the Files SDK with the iDrive e2 adapter. Credentials are automatically loaded from environment variables.

```ts
import { Files } from "files-sdk";
import { idriveE2 } from "files-sdk/idrive-e2";

const files = new Files({
  adapter: idriveE2({
    bucket: "uploads",
    endpoint: "https://q9z7.va.idrivee2-NN.com",
    // accessKeyId / secretAccessKey auto-loaded from
    // IDRIVE_E2_ACCESS_KEY_ID / IDRIVE_E2_SECRET_ACCESS_KEY
  }),
});
```

--------------------------------

### Configure MCP server in Claude Code

Source: https://files-sdk.dev/docs/cli/mcp

Example configuration for integrating the files MCP server into a Claude Code environment file.

```jsonc
// Wire it into Claude Code (~/.claude.json or .claude/mcp.json)
{
  "mcpServers": {
    "files-sdk": {
      "command": "files",
      "args": ["--provider", "s3", "--bucket", "uploads", "mcp"],
      "env": {
        "AWS_ACCESS_KEY_ID": "...",
        "AWS_SECRET_ACCESS_KEY": "...",
      },
    },
  },
}
```

--------------------------------

### Wasabi Adapter Initialization

Source: https://files-sdk.dev/docs/adapters/wasabi

How to initialize the Files SDK with the Wasabi adapter.

```APIDOC
## Initialization

### Description
Initialize the Files SDK using the Wasabi adapter. The adapter automatically loads credentials from `WASABI_ACCESS_KEY_ID` and `WASABI_SECRET_ACCESS_KEY` environment variables.

### Usage
```ts
import { Files } from "files-sdk";
import { wasabi } from "files-sdk/wasabi";

const files = new Files({
  adapter: wasabi({
    bucket: "uploads",
    region: "us-east-1"
  }),
});
```
```

--------------------------------

### Configure signedUrlPolicy plugin

Source: https://files-sdk.dev/docs/plugins/signed-url-policy

Place the plugin at the start of the plugins array to ensure it intercepts URL generation requests before they reach the adapter.

```ts
plugins: [signedUrlPolicy({ maxExpiresIn: 900 }), encryption(key)];
```

--------------------------------

### Initialize Tigris adapter

Source: https://files-sdk.dev/docs/adapters/tigris

Configure the Files SDK to use the Tigris adapter by providing the bucket name. Credentials are automatically loaded from environment variables.

```typescript
import { Files } from "files-sdk";
import { tigris } from "files-sdk/tigris";

const files = new Files({
  adapter: tigris({
    bucket: "uploads",
    // endpoint defaults to https://fly.storage.tigris.dev
    // region defaults to "auto" (Tigris routes globally)
    // accessKeyId / secretAccessKey auto-loaded from
    // TIGRIS_ACCESS_KEY_ID / TIGRIS_SECRET_ACCESS_KEY
  }),
});
```

--------------------------------

### Start the MCP server via CLI

Source: https://files-sdk.dev/docs/cli/mcp

Commands to launch the MCP server on stdio, either in read-only mode or with mutation tools enabled.

```bash
# Start the read-only MCP server on stdio
files --provider s3 --bucket uploads mcp

# Opt into mutation tools
files --provider s3 --bucket uploads mcp --allow-writes
```

--------------------------------

### Initialize SharePoint adapter

Source: https://files-sdk.dev/docs/adapters/sharepoint

Configure the Files instance with the SharePoint adapter, providing site URL, library name, and client credentials.

```ts
import { Files } from "files-sdk";
import { sharepoint } from "files-sdk/sharepoint";

const files = new Files({
  adapter: sharepoint({
    siteUrl: "https://contoso.sharepoint.com/sites/marketing",
    documentLibrary: "Reports", // optional, omit for default library
    clientCredentials: {
      tenantId: process.env.SHAREPOINT_TENANT_ID!,
      clientId: process.env.SHAREPOINT_CLIENT_ID!,
      clientSecret: process.env.SHAREPOINT_CLIENT_SECRET!,
    },
    rootFolderPath: "Uploads",
  }),
});
```

--------------------------------

### Mounting the Files gateway in a SvelteKit +server.ts endpoint

Source: https://files-sdk.dev/docs/ui/server/sveltekit

Use createRouteHandler to export the necessary GET, POST, and PUT methods for the SvelteKit server route.

```ts
import { createFiles } from "files-sdk";
import { s3 } from "files-sdk/s3";
import { createFilesRouter } from "files-sdk/api";
import { createRouteHandler } from "files-sdk/sveltekit";

const router = createFilesRouter({
  files: createFiles({ adapter: s3({ bucket: "uploads" }) }),
  allowedOrigins: ["https://app.example.com"],
  authorize: async ({ req }) => {
    /* throw to deny, or return a per-user constraint — see /ui/server/authorization */
  },
});

export const { GET, POST, PUT } = createRouteHandler(router);
```

--------------------------------

### Mounting the Files gateway in Hono

Source: https://files-sdk.dev/docs/ui/server/hono

Use createRouteHandler to mount the Files router to a specific path in a Hono application. The handler manages GET, POST, and PUT requests internally.

```ts
import { Hono } from "hono";
import { createFiles } from "files-sdk";
import { s3 } from "files-sdk/s3";
import { createFilesRouter } from "files-sdk/api";
import { createRouteHandler } from "files-sdk/hono";

const router = createFilesRouter({
  files: createFiles({ adapter: s3({ bucket: "uploads" }) }),
  allowedOrigins: ["https://app.example.com"],
  authorize: async ({ req }) => {
    /* throw to deny, or return a per-user constraint — see /ui/server/authorization */
  },
});

const app = new Hono();
app.all("/api/files", createRouteHandler(router));

export default app;
```

--------------------------------

### Initialize Supabase Adapter

Source: https://files-sdk.dev/docs/adapters/supabase

Configure the Files SDK with the Supabase adapter. Environment variables are auto-loaded, or a client can be passed manually.

```typescript
import { Files } from "files-sdk";
import { supabase } from "files-sdk/supabase";

const files = new Files({
  adapter: supabase({
    bucket: "uploads",
    // Auto-loads url + key from SUPABASE_URL / NEXT_PUBLIC_SUPABASE_URL
    // and SUPABASE_SERVICE_ROLE_KEY / SUPABASE_KEY /
    // NEXT_PUBLIC_SUPABASE_ANON_KEY. Or pass an existing SupabaseClient
    // via `client` to share with auth/postgrest.
  }),
});
```

--------------------------------

### Initialize useFiles Hook

Source: https://files-sdk.dev/docs/ui/client/react

Configure the hook with an endpoint and dynamic headers for authentication.

```tsx
const files = useFiles({
  endpoint: "/api/files", // default "/api/files"
  headers: () => ({ authorization: token }), // sent on every call (static or lazy)
});
```

--------------------------------

### Serve Files gateway with Bun.serve

Source: https://files-sdk.dev/docs/ui/server/bun

Integrate the Files gateway directly into a Bun server by passing the router handle to a route. This setup uses the standard Web fetch handler pattern.

```ts
import { createFiles } from "files-sdk";
import { s3 } from "files-sdk/s3";
import { createFilesRouter } from "files-sdk/api";

const router = createFilesRouter({
  files: createFiles({ adapter: s3({ bucket: "uploads" }) }),
  allowedOrigins: ["https://app.example.com"],
  authorize: async ({ req }) => {
    /* throw to deny, or return a per-user constraint — see /ui/server/authorization */
  },
});

Bun.serve({
  port: 3000,
  routes: {
    // A bare handler runs for every method; the gateway dispatches internally
    // (GET = download, POST = the JSON verbs, PUT = upload).
    "/api/files": (req) => router.handle(req),
  },
});
```
Tokens:
Raw