Registry / storage / files-sdk

files-sdk

JSON →
library1.8.0jsnpmunverified

Unified storage SDK for object/blob backends v1.8.0. Provides a single, tree-shakeable API across 20+ providers (S3, GCS, Azure, R2, Vercel Blob, Dropbox, etc.) with web-standard I/O and an escape hatch to native clients. Each adapter is a separate entry point; only peer dependencies you install are bundled. Active development with regular releases. Key differentiator: one consistent interface for both cloud storage and consumer services, with AI tool integrations for Vercel AI SDK, OpenAI Agents, and Claude Agent SDK.

npm install files-sdk
INSTALL
IMPORT
SIG · FILES-SDK
F
files-sdk
storagejavascriptv1.8.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Files
import { Files } from 'files-sdk'
const Files = require('files-sdk')
ESM-only package; named export, not default.
s3
import { s3 } from 'files-sdk/s3'
import { s3 } from 'files-sdk'
Each adapter is a separate entry point under 'files-sdk/<provider>'. Check docs for exact path.
file
import { Files } from 'files-sdk' const files = new Files({ adapter: s3({ bucket: 'x' }) })
import { file } from 'files-sdk/file'
File handles are returned by files.file(key), not imported directly.

Shows basic usage: import Files and S3 adapter, upload, download, check existence, generate signed URL, list, delete, and use file handles.

import { Files } from 'files-sdk'; import { s3 } from 'files-sdk/s3'; const files = new Files({ adapter: s3({ bucket: 'my-bucket' }), }); // Upload a file await files.upload('path/to/hello.txt', new Blob(['Hello world']), { contentType: 'text/plain', }); // Download const blob = await files.download('path/to/hello.txt'); // Check existence const exists = await files.exists('path/to/hello.txt'); // Get a signed URL (expires in 1 hour) const url = await files.url('path/to/hello.txt', { expiresIn: 3600 }); // List files (paginated) for await (const entry of files.list({ prefix: 'path/' })) { console.log(entry.key); } // Delete await files.delete('path/to/hello.txt'); // Use a file handle for repeated operations const avatar = files.file('avatars/user1.png'); await avatar.upload(new Blob([...]), { contentType: 'image/png' }); console.log(await avatar.head()); await avatar.delete();
Debug
Known issues
breakingAdapter imports changed from default exports to named exports in v1.0.0.
fix
Use `import { s3 } from 'files-sdk/s3'` instead of `import s3 from 'files-sdk/s3'`.
affects: <1.0.0
breakingThe `list` method now returns an async iterable instead of an array in v1.5.0.
fix
Use `for await (const entry of files.list(...))` instead of `await files.list(...).then(arr => ...)`.
affects: <1.5.0
deprecatedThe `signedUploadUrl` method is deprecated; use `url({ method: 'PUT' })` instead.
fix
Replace `files.signedUploadUrl(key, options)` with `files.url(key, { ...options, method: 'PUT' })`.
affects: >=1.6.0
gotchaMissing peer dependencies cause runtime errors with unclear stack traces.
fix
Install the required peer dependency for your chosen adapter. The error message will specify the missing package (e.g., `ERR_MODULE_NOT_FOUND` for `@aws-sdk/client-s3`).
affects: >=0.0.0
gotchaBodies must be web-standard types (Blob, File, ReadableStream, etc.); passing Node.js Buffer may fail in edge runtimes.
fix
Convert Buffer to Uint8Array or Blob before uploading. Example: `new Blob([buffer])`.
affects: >=0.0.0
Errors
Common errors & fixes
ERR_MODULE_NOT_FOUND: Cannot find package '@aws-sdk/client-s3'
Missing peer dependency for S3 adapter.
fix
Run `npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner` alongside `files-sdk`.
TypeError: files.url is not a function
Using an older version of files-sdk that does not implement url() for all adapters.
fix
Update to files-sdk v1.4.0 or later, or check adapter-specific compatibility.
Error: The adapter 'gcs' is not found. Did you mean to import from 'files-sdk/gcs'?
Importing adapter from wrong path (e.g., 'files-sdk/gcp').
fix
Use `import { gcs } from 'files-sdk/gcs'` and install the required GCS peer dependencies.
Upgrade
Version history
1.8.0latest on npm
Audit
Dependencies
@anthropic-ai/claude-agent-sdkoptionalPeer dependency for Claude AI adapter
@aws-sdk/client-s3optionalPeer dependency for S3 adapter
@aws-sdk/lib-storageoptionalPeer dependency for S3 adapter
@aws-sdk/s3-presigned-postoptionalPeer dependency for S3 adapter
@aws-sdk/s3-request-presigneroptionalPeer dependency for S3 adapter
@azure/core-authoptionalPeer dependency for Azure adapter
@azure/identityoptionalPeer dependency for Azure adapter
@azure/storage-bloboptionalPeer dependency for Azure adapter
@bunny.net/storage-sdkoptionalPeer dependency for Bunny.net adapter
@google-cloud/storageoptionalPeer dependency for GCS adapter
@googleapis/driveoptionalPeer dependency for Google Drive adapter
@microsoft/microsoft-graph-clientoptionalPeer dependency for OneDrive adapter
@netlify/blobsoptionalPeer dependency for Netlify Blobs adapter
@openai/agentsoptionalPeer dependency for OpenAI Agents adapter
@opentelemetry/apioptionalPeer dependency for instrumentation
@supabase/storage-jsoptionalPeer dependency for Supabase adapter
@vercel/bloboptionalPeer dependency for Vercel Blob adapter
aioptionalPeer dependency for Vercel AI SDK adapter
basic-ftpoptionalPeer dependency for FTP adapter
box-typescript-sdk-genoptionalPeer dependency for Box adapter
cloudinaryoptionalPeer dependency for Cloudinary adapter
convexoptionalPeer dependency for Convex adapter
dropboxoptionalPeer dependency for Dropbox adapter
firebase-adminoptionalPeer dependency for Firebase adapter
google-auth-libraryoptionalPeer dependency for GCS adapter
node-appwriteoptionalPeer dependency for Appwrite adapter
openaioptionalPeer dependency for OpenAI adapter
pocketbaseoptionalPeer dependency for PocketBase adapter
ssh2-sftp-clientoptionalPeer dependency for SFTP adapter
uploadthingoptionalPeer dependency for UploadThing adapter
zodoptionalPeer dependency for validation
Agent activity
31 hits · last 30 days
node
28
Resources
files-sdk — npm install files-sdk · libregistry