Vercel Blob

Vercel Blob. Prefers auto-rotating Vercel OIDC (VERCEL_OIDC_TOKEN + BLOB_STORE_ID), falls back to BLOB_READ_WRITE_TOKEN, or pass credentials manually.

Installation

@vercel/blob is an optional peer dependency of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @vercel/blob

pnpm add files-sdk @vercel/blob

yarn add files-sdk @vercel/blob

bun add files-sdk @vercel/blob

nub add files-sdk @vercel/blob

aube add files-sdk @vercel/blob

Usage

On Vercel, the adapter prefers Vercel’s OIDC authentication when VERCEL_OIDC_TOKEN and BLOB_STORE_ID are present (both are auto-injected when the Blob store is connected to the project). OIDC tokens rotate automatically, so they remove the risk that a long-lived secret leaks from the codebase or environment. Off Vercel - or if OIDC isn’t configured - the adapter falls back to BLOB_READ_WRITE_TOKEN. An explicit token option always wins.

import { Files } from "files-sdk";
import { vercelBlob } from "files-sdk/vercel-blob";

// On Vercel: VERCEL_OIDC_TOKEN + BLOB_STORE_ID are auto-injected when the
// Blob store is connected to the project (OIDC, recommended). Off Vercel,
// or as a fallback, BLOB_READ_WRITE_TOKEN is used.
const files = new Files({ adapter: vercelBlob() });

Pass oidcToken and storeId directly for runtimes that don’t expose process.env (Vite, etc.), or to bypass env detection entirely:

// Frameworks that don't load .env.local into process.env (Vite, etc.)
// need OIDC credentials passed explicitly.
const files = new Files({
  adapter: vercelBlob({
    oidcToken: loadOidcToken(),
    storeId: loadStoreId(),
  }),
});

downloadTimeoutMs bounds the body reads issued by download() and the lazy bodies returned from head()/list() (the public-URL fetch, or blob.get() in private mode). Defaults to 5 minutes; pass 0 to disable. A hung CDN response would otherwise leak a fetch that never resolves.

access selects public or private blobs and is fixed at construction. Defaults to "public". With access: "private", uploads use Vercel’s private mode and reads route through blob.get() with whichever credentials the adapter resolved (OIDC or read-write token) instead of a public URL fetch. There is no permanent public URL for private blobs, so url() mints a Vercel Signed URL instead - a presigned GET scoped to that key that expires after expiresIn seconds (1 hour by default, defaultUrlExpiresIn changes the default). Need both? Use two adapters.

Signed URLs

Vercel Signed URLs (@vercel/blob 2.4.0+) back two methods:

• url() in private mode issues a signed token scoped to the key and the get operation, expiring with the URL, then signs the URL locally. One control-API round trip per call. Vercel caps the lifetime at 7 days server-side.
• signedUploadUrl() in either mode returns a presigned PUT. contentType and maxSize are enforced by Vercel’s CDN, so they are real constraints, not advisory headers. There is no minimum-size counterpart: a positive minSize throws rather than handing out a URL that accepts the empty upload you asked to reject. The adapter’s addRandomSuffix and allowOverwrite settings apply to the upload.

const files = new Files({ adapter: vercelBlob({ access: "private" }) });

// Presigned GET, valid for five minutes.
const url = await files.url("invoices/2026-q1.pdf", { expiresIn: 300 });

// Presigned PUT the browser can use directly; Vercel rejects other
// content types and anything over 10 MB at the CDN.
const upload = await files.signedUploadUrl("uploads/photo.png", {
  contentType: "image/png",
  expiresIn: 600,
  maxSize: 10 * 1024 * 1024,
});
// → { method: "PUT", url, headers: { "Content-Type": "image/png" } }

Public blobs keep returning their permanent CDN URL from url() - a presigned copy would add a round trip without restricting anything - so capabilities.signedUrl.supported is true only in private mode. Neither the CDN URL nor a presigned URL can carry a Content-Disposition override, so responseContentDisposition throws in both modes.

Options

Limitations

User metadata isn’t supported by the underlying API, so passing a non-empty metadata throws rather than silently dropping it. cacheControl is supported through its max-age directive, which maps to the blob’s cacheControlMaxAge; Vercel writes the rest of the header itself. A value with no max-age (e.g. "no-store") throws rather than being dropped.

With allowOverwrite: false, uploading to an existing key throws a Conflict.

Compatibility

Public access

Private access