{"id":47678,"library":"files-sdk","title":"Files SDK","description":"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.","status":"active","version":"1.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/haydenbleasel/files-sdk","tags":["javascript","typescript"],"install":[{"cmd":"npm install files-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add files-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add files-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Claude AI adapter","package":"@anthropic-ai/claude-agent-sdk","optional":true},{"reason":"Peer dependency for S3 adapter","package":"@aws-sdk/client-s3","optional":true},{"reason":"Peer dependency for S3 adapter","package":"@aws-sdk/lib-storage","optional":true},{"reason":"Peer dependency for S3 adapter","package":"@aws-sdk/s3-presigned-post","optional":true},{"reason":"Peer dependency for S3 adapter","package":"@aws-sdk/s3-request-presigner","optional":true},{"reason":"Peer dependency for Azure adapter","package":"@azure/core-auth","optional":true},{"reason":"Peer dependency for Azure adapter","package":"@azure/identity","optional":true},{"reason":"Peer dependency for Azure adapter","package":"@azure/storage-blob","optional":true},{"reason":"Peer dependency for Bunny.net adapter","package":"@bunny.net/storage-sdk","optional":true},{"reason":"Peer dependency for GCS adapter","package":"@google-cloud/storage","optional":true},{"reason":"Peer dependency for Google Drive adapter","package":"@googleapis/drive","optional":true},{"reason":"Peer dependency for OneDrive adapter","package":"@microsoft/microsoft-graph-client","optional":true},{"reason":"Peer dependency for Netlify Blobs adapter","package":"@netlify/blobs","optional":true},{"reason":"Peer dependency for OpenAI Agents adapter","package":"@openai/agents","optional":true},{"reason":"Peer dependency for instrumentation","package":"@opentelemetry/api","optional":true},{"reason":"Peer dependency for Supabase adapter","package":"@supabase/storage-js","optional":true},{"reason":"Peer dependency for Vercel Blob adapter","package":"@vercel/blob","optional":true},{"reason":"Peer dependency for Vercel AI SDK adapter","package":"ai","optional":true},{"reason":"Peer dependency for FTP adapter","package":"basic-ftp","optional":true},{"reason":"Peer dependency for Box adapter","package":"box-typescript-sdk-gen","optional":true},{"reason":"Peer dependency for Cloudinary adapter","package":"cloudinary","optional":true},{"reason":"Peer dependency for Convex adapter","package":"convex","optional":true},{"reason":"Peer dependency for Dropbox adapter","package":"dropbox","optional":true},{"reason":"Peer dependency for Firebase adapter","package":"firebase-admin","optional":true},{"reason":"Peer dependency for GCS adapter","package":"google-auth-library","optional":true},{"reason":"Peer dependency for Appwrite adapter","package":"node-appwrite","optional":true},{"reason":"Peer dependency for OpenAI adapter","package":"openai","optional":true},{"reason":"Peer dependency for PocketBase adapter","package":"pocketbase","optional":true},{"reason":"Peer dependency for SFTP adapter","package":"ssh2-sftp-client","optional":true},{"reason":"Peer dependency for UploadThing adapter","package":"uploadthing","optional":true},{"reason":"Peer dependency for validation","package":"zod","optional":true}],"imports":[{"note":"ESM-only package; named export, not default.","wrong":"const Files = require('files-sdk')","symbol":"Files","correct":"import { Files } from 'files-sdk'"},{"note":"Each adapter is a separate entry point under 'files-sdk/<provider>'. Check docs for exact path.","wrong":"import { s3 } from 'files-sdk'","symbol":"s3","correct":"import { s3 } from 'files-sdk/s3'"},{"note":"File handles are returned by files.file(key), not imported directly.","wrong":"import { file } from 'files-sdk/file'","symbol":"file","correct":"import { Files } from 'files-sdk'  const files = new Files({ adapter: s3({ bucket: 'x' }) })"}],"quickstart":{"code":"import { Files } from 'files-sdk';\nimport { s3 } from 'files-sdk/s3';\n\nconst files = new Files({\n  adapter: s3({ bucket: 'my-bucket' }),\n});\n\n// Upload a file\nawait files.upload('path/to/hello.txt', new Blob(['Hello world']), {\n  contentType: 'text/plain',\n});\n\n// Download\nconst blob = await files.download('path/to/hello.txt');\n\n// Check existence\nconst exists = await files.exists('path/to/hello.txt');\n\n// Get a signed URL (expires in 1 hour)\nconst url = await files.url('path/to/hello.txt', { expiresIn: 3600 });\n\n// List files (paginated)\nfor await (const entry of files.list({ prefix: 'path/' })) {\n  console.log(entry.key);\n}\n\n// Delete\nawait files.delete('path/to/hello.txt');\n\n// Use a file handle for repeated operations\nconst avatar = files.file('avatars/user1.png');\nawait avatar.upload(new Blob([...]), { contentType: 'image/png' });\nconsole.log(await avatar.head());\nawait avatar.delete();","lang":"typescript","description":"Shows basic usage: import Files and S3 adapter, upload, download, check existence, generate signed URL, list, delete, and use file handles."},"warnings":[{"fix":"Use `import { s3 } from 'files-sdk/s3'` instead of `import s3 from 'files-sdk/s3'`.","message":"Adapter imports changed from default exports to named exports in v1.0.0.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use `for await (const entry of files.list(...))` instead of `await files.list(...).then(arr => ...)`.","message":"The `list` method now returns an async iterable instead of an array in v1.5.0.","severity":"breaking","affected_versions":"<1.5.0"},{"fix":"Replace `files.signedUploadUrl(key, options)` with `files.url(key, { ...options, method: 'PUT' })`.","message":"The `signedUploadUrl` method is deprecated; use `url({ method: 'PUT' })` instead.","severity":"deprecated","affected_versions":">=1.6.0"},{"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`).","message":"Missing peer dependencies cause runtime errors with unclear stack traces.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Convert Buffer to Uint8Array or Blob before uploading. Example: `new Blob([buffer])`.","message":"Bodies must be web-standard types (Blob, File, ReadableStream, etc.); passing Node.js Buffer may fail in edge runtimes.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'20':18 'across':17 'activ':54 'adapt':41 'agent':80,83 'ai':72,77 'api':16 'azur':22 'backend':8 'blob':25 'bundl':53 'claud':82 'client':39 'cloud':66 'consist':62 'consum':69 'depend':49 'develop':55 'differenti':60 'dropbox':26 'entri':45 'escap':35 'etc':27 'file':1 'gcs':21 'hatch':36 'i/o':32 'instal':51 'integr':74 'interfac':63 'javascript':85 'key':59 'nativ':38 'object/blob':7 'one':61 'openai':79 'peer':48 'point':46 'provid':10,19 'r2':23 'regular':57 'releas':58 's3':20 'sdk':2,5,78,84 'separ':44 'servic':70 'shakeabl':15 'singl':12 'standard':31 'storag':4,67 'tool':73 'tree':14 'tree-shak':13 'typescript':86 'unifi':3 'v1.8.0':9 'vercel':24,76 'web':30 'web-standard':29","created_at":"2026-06-07T16:52:44.844240+00:00","updated_at":"2026-06-07T16:52:44.844240+00:00","problems":[{"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`.","cause":"Missing peer dependency for S3 adapter.","error":"ERR_MODULE_NOT_FOUND: Cannot find package '@aws-sdk/client-s3'"},{"fix":"Update to files-sdk v1.4.0 or later, or check adapter-specific compatibility.","cause":"Using an older version of files-sdk that does not implement url() for all adapters.","error":"TypeError: files.url is not a function"},{"fix":"Use `import { gcs } from 'files-sdk/gcs'` and install the required GCS peer dependencies.","cause":"Importing adapter from wrong path (e.g., 'files-sdk/gcp').","error":"Error: The adapter 'gcs' is not found. Did you mean to import from 'files-sdk/gcs'?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/haydenbleasel/files-sdk#readme","github":"https://github.com/haydenbleasel/files-sdk","docs":null,"changelog":null,"pypi":null,"npm":"files-sdk","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}