Vercel Blob

@vercel/blob is the official JavaScript/TypeScript client for Vercel Blob, a managed object storage service built for storing and serving files at the edge. It provides a small, consistent function-based API — put, get, head, list, del, copy, rename, putImage, putFromUrl, and createFolder — for uploading and managing public or private blobs, with built-in retry handling, upload progress callbacks, and typed error classes for every failure mode the API can return.

Beyond simple server-side uploads, the package ships a dedicated client entrypoint (@vercel/blob/client) for uploading directly from a browser using short-lived client tokens, and a full multipart upload system — either as a single multipart: true flag on put() or as manual createMultipartUpload/uploadPart/completeMultipartUpload primitives — for reliably transferring very large files in parallel, resumable chunks. Authentication supports read-write tokens, Vercel OIDC tokens, and scoped client/presigned tokens, so the same API works whether it’s called from a Vercel-hosted server, an edge function, or a browser.

What You Get

• A functional API (put, get, head, list, del, copy, rename) covering the full blob lifecycle with consistent, shared options across every command
• A dedicated client-upload entrypoint for uploading large files directly from the browser using short-lived client tokens, bypassing server request-size limits
• A three-tier multipart upload system: a simple multipart: true flag, manual create/uploadPart/complete primitives, and a convenience createMultipartUploader wrapper
• Typed error classes (BlobNotFoundError, BlobAccessError, BlobServiceRateLimited, BlobFileTooLargeError, etc.) mapped directly from the API’s error codes for precise error handling
• Built-in retry with exponential backoff via async-retry, automatic environment detection (Node/undici vs. browser fetch/crypto/stream shims), and upload progress callbacks

Common Use Cases

• Uploading user-generated files (avatars, attachments, exports) from a Next.js or other server route straight to durable object storage
• Letting users upload large files (videos, datasets) directly from the browser without routing bytes through your own server’s request-size limits
• Reliably transferring very large files with multipart/parallel chunked uploads and automatic retry of failed parts
• Generating public download URLs for static assets or private, authenticated URLs for gated content
• Managing a store programmatically — listing, renaming, copying, or deleting blobs as part of a content pipeline or admin tool

Under The Hood

Architecture The package exposes a functional API (put, get, head, list, del, copy, rename, createFolder) built via factory functions (createPutMethod, createCreateMultipartUploadMethod, createUploadPartMethod, createCompleteMultipartUploadMethod) that all share one core request pipeline in api.ts, layered over a low-level blobRequest wrapper in request.ts that abstracts fetch/undici/XHR per environment. Auth resolution (resolveBlobAuth in helpers.ts) supports read-write tokens, OIDC tokens, and presigned/client tokens uniformly across every command. The multipart/ subdirectory factors upload orchestration (create, upload, complete, uncontrolled, create-uploader) out as a separate concern from single-shot put, and client.ts re-exposes a browser-only surface built from the same factories with a narrower set of allowed options. Because none of put/get/head/list/del/copy/rename implement their own HTTP handling, changing the retry/error-mapping logic in api.ts ripples through every command uniformly.

Tech Stack TypeScript built with tsup into dual ESM/CJS output (via package.json exports and typesVersions), using undici for Node fetch with a browser field swap to native fetch/crypto/stream shims for bundlers and Vite; retry logic via async-retry; token verification via @vercel/oidc. Tests run under Jest across three separate environments — plain Node, @edge-runtime/jest-environment for Edge, and jsdom for browser — via dedicated test:node/test:edge/test:browser scripts. The monorepo is orchestrated with Turborepo and pnpm workspaces, formatted and linted with Biome, versioned and published via Changesets, and gated by Husky/lint-staged pre-commit hooks plus separate GitHub Actions workflows for unit tests, dev and live integration tests, and scheduled visual tests.

Code Quality Testing is extensive and environment-aware: many modules split their test file into .node.test.ts/.edge.test.ts/.browser.test.ts variants (e.g. client, signed-token) so behavior is verified separately per runtime target, with a shared spec file reused across environments to avoid duplicated assertions. Error handling is explicit and typed — a dedicated hierarchy of BlobError subclasses maps server error codes to specific exception types in getBlobError, and the request pipeline distinguishes retryable network/service errors from non-retryable client errors (aborted requests, malformed input, suspended stores) via async-retry’s bail(). Naming is consistent across the codebase (createXMethod factories, XCommandOptions types), every public function ships its own exported types, and CI runs unit, dev integration, live integration, and scheduled visual test suites.

API Design The public surface is intentionally small and consistent — put/get/head/list/del/copy/rename/putImage/putFromUrl/createFolder all share the same options shape (access, token, abortSignal, cacheControlMaxAge), so learning one command transfers directly to the rest. Multipart uploads are exposed at three levels of abstraction — a single flag, manual primitives, and a convenience wrapper — letting simple use cases stay simple while advanced ones keep full control. Client-side uploads use signed tokens with pathname and content-type constraints enforced server-side, avoiding the need to proxy large file bodies through a developer’s own server, a genuine ergonomic advantage over generic S3-style SDKs, though the differentiated token model does add its own upfront learning curve.