Vercel Blob

Store files in Vercel Blob with files-sdk, using OIDC on Vercel (BLOB_STORE_ID, no secret) or a BLOB_READ_WRITE_TOKEN anywhere, public or private.

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

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

// On Vercel, the connected Blob store authenticates through OIDC. Anywhere
// else, set BLOB_READ_WRITE_TOKEN. No options needed for either.
const files = new Files({ adapter: vercelBlob() });

await files.upload("avatars/abc.png", file);
const url = await files.url("avatars/abc.png");

Authentication

Vercel Blob takes one of two credentials, and the adapter picks whichever it finds without any options:

OIDC on Vercel

OIDC needs no secret in your code or your environment variables. Connect the Blob store to the project in the Vercel dashboard, and the deployment gets BLOB_STORE_ID plus an OIDC token that Vercel rotates on its own. On Vercel Functions the token arrives with each request, in the x-vercel-oidc-token header, rather than as an environment variable. The adapter hands just the store id to @vercel/blob, which reads the current token from the request on every call, so vercelBlob() works the same at module scope as inside a handler. That holds when the project also has BLOB_READ_WRITE_TOKEN: the request’s OIDC token is used first.

Because the token is short-lived, a leaked one stops working within hours, where a leaked read-write token works until you rotate it by hand.

Read-write token

A read-write token grants full access to one store and doesn’t expire. Find it on the store’s page in the Vercel dashboard (Storage, then your Blob store), or run vercel env pull in a linked project to write it to .env.local. Set it as BLOB_READ_WRITE_TOKEN, or pass it as token:

const files = new Files({
  adapter: vercelBlob({ token: process.env.BLOB_READ_WRITE_TOKEN }),
});

Keep it on the server. To let a browser upload, hand it a signed upload URL or put the gateway in front of the adapter, and never ship the token itself.

Local development

vercel env pull writes VERCEL_OIDC_TOKEN and BLOB_STORE_ID to .env.local, so OIDC works locally too. The local token expires after 12 hours. @vercel/blob 2.5 and later refresh it automatically in a project linked with vercel link; on 2.4, run vercel env pull again. A read-write token in .env.local works as well and never expires.

If your framework doesn’t load .env.local into process.env (Vite, for example), pass the values explicitly:

const files = new Files({
  adapter: vercelBlob({
    oidcToken: import.meta.env.VERCEL_OIDC_TOKEN,
    storeId: import.meta.env.BLOB_STORE_ID,
  }),
});

An explicit oidcToken is used as given, so it isn’t refreshed.

Which credential wins

The adapter follows @vercel/blob’s own order, checked on every call:

1. A token option.
2. An oidcToken option, with storeId (option or BLOB_STORE_ID).
3. An OIDC token @vercel/blob finds itself, with storeId (option or BLOB_STORE_ID): the request’s x-vercel-oidc-token header first, then VERCEL_OIDC_TOKEN.
4. BLOB_READ_WRITE_TOKEN.

With BLOB_STORE_ID and BLOB_READ_WRITE_TOKEN both set, a Vercel Function authenticates with the request’s OIDC token, and the read-write token is used only where no OIDC token turns up, such as a script or a server outside Vercel. Without a store id there is no OIDC, so the read-write token is used even inside a request.

Credential errors

• vercelBlob adapter: missing credentials means nothing could authenticate. The adapter throws it when created with none of token, oidcToken, BLOB_READ_WRITE_TOKEN, or BLOB_STORE_ID available. With only a store id, it can’t know yet whether an OIDC token will arrive, so the first operation that finds none throws it instead (@vercel/blob’s own “No blob credentials found” error is its cause). That’s typically code running outside Vercel, or outside a request on Vercel, for example at import time. Off Vercel, set BLOB_READ_WRITE_TOKEN or run vercel env pull. On Vercel, check that the Blob store is connected to the project and environment you deployed.
• `oidcToken` was passed but no `storeId` was found means OIDC was requested explicitly without a store id. Pass storeId or set BLOB_STORE_ID.
• A 401 or Unauthorized error with OIDC locally usually means the local token expired. Run vercel env pull again, or upgrade to @vercel/blob 2.5 or later. A token passed as oidcToken is never refreshed.

Public and private blobs

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.

downloadTimeoutMs bounds the body reads issued by download() (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.

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 Unsupported 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. In public mode, url(key, { expiresIn }) throws Unsupported rather than hand back a link that never expires; omit expiresIn for the permanent URL. Neither the CDN URL nor a presigned URL can carry a Content-Disposition override, so responseContentDisposition throws Unsupported in both modes.

Signed uploads don’t depend on the mode: capabilities.signedUpload reports supported, maxSize, and contentType as true for public and private adapters alike. The gateway presigns on that, so browser uploads go straight to Vercel Blob with a presigned PUT in either mode, with your maxUploadSize and the file’s content type enforced at the CDN, rather than streaming through your server.

Options

Limitations

User metadata isn’t supported by the underlying API, so passing a non-empty metadata throws Unsupported 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 Unsupported rather than being dropped.

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

Compatibility

Public access

Private access