Vercel Blob Storage

Just need ad-hoc uploads? Wrap this adapter in the Files facade for a one-liner API. The reference below shows direct adapter usage — pick that path when you're hosting an upload server.

Overview

Vercel Blob Storage is a serverless object storage service optimized for edge deployments. It provides fast, global access to files with automatic CDN distribution.

Installation

npm install @vercel/blob

yarn add @vercel/blob

pnpm add @vercel/blob

Usage

On Vercel (recommended): OIDC

When a Blob store is connected to a Vercel project, VERCEL_OIDC_TOKEN and BLOB_STORE_ID are auto-injected. OIDC tokens are short-lived and auto-rotated, so there's no long-lived secret to leak.

import { VercelBlobStorage } from "@visulima/storage/provider/vercel";

// Zero config — picks up VERCEL_OIDC_TOKEN + BLOB_STORE_ID from process.env.
const storage = new VercelBlobStorage({
    metaStorageConfig: { directory: "/tmp/upload-metafiles" },
});

For runtimes that don't expose process.env (Vite, some edge sandboxes), pass the OIDC pair explicitly:

const storage = new VercelBlobStorage({
    oidcToken: loadOidcToken(),
    storeId: loadStoreId(), // accepts "store_<id>" or "<id>"
});

See Vercel's OIDC docs for the full background.

Off Vercel: read-write token

For CI, local dev, or anything not running on Vercel, use a long-lived BLOB_READ_WRITE_TOKEN:

const storage = new VercelBlobStorage({
    token: process.env.BLOB_READ_WRITE_TOKEN,
    metaStorageConfig: { directory: "/tmp/upload-metafiles" },
});

Configuration

Credential precedence

The adapter resolves auth credentials in this order — first match wins:

1. Explicit token option (RW or client token).
2. OIDC pair: oidcToken + storeId (option or VERCEL_OIDC_TOKEN + BLOB_STORE_ID env).
3. BLOB_READ_WRITE_TOKEN / VERCEL_BLOB_TOKEN env.

If no credentials are found, the constructor throws. Partial OIDC config (only one of oidcToken/storeId set) also throws, so misconfiguration fails loudly instead of silently falling through to anonymous calls.

Environment Variables

Advanced Configuration

const storage = new VercelBlobStorage({
    // Auth (pick one of token / oidcToken+storeId; otherwise env vars are used)
    token: process.env.BLOB_READ_WRITE_TOKEN,

    multipart: true, // Enable multipart uploads for large files
    multipart: 10 * 1024 * 1024, // Or: enable multipart for files > 10MB

    retryConfig: {
        maxRetries: 3,
        initialDelay: 1000,
    },
    expiration: {
        maxAge: "7d",
        purgeInterval: "1h",
    },
});

Peer dependency

OIDC support requires @vercel/blob >= 2.4.0 (the first release with oidcToken and storeId on BlobCommandOptions).

Features

• Global CDN: Automatic CDN distribution for fast access
• Serverless: Optimized for edge deployments
• Multipart Uploads: Support for large files
• Automatic Retry: Built-in retry mechanism for transient failures

Basic Operations

// Create a file
const file = await storage.create({
    contentType: "image/jpeg",
    metadata: { filename: "photo.jpg" },
});

// Write data
await storage.write({
    id: file.id,
    body: imageStream,
    contentLength: imageSize,
});

// Get file
const fileData = await storage.get({ id: file.id });

// Delete file
await storage.delete({ id: file.id });

URL Generation

Vercel Blob automatically generates public URLs:

const file = await storage.get({ id: "file-id" });

// file.url - Public URL
// file.downloadUrl - Download URL
// file.pathname - File pathname

Best Practices

1. Prefer OIDC on Vercel - Use VERCEL_OIDC_TOKEN + BLOB_STORE_ID over long-lived BLOB_READ_WRITE_TOKEN. OIDC tokens auto-rotate and can't leak from a checked-in env file.
2. Use environment variables - Store tokens securely off Vercel.
3. Enable multipart for large files - Better performance for files > 10MB.
4. Configure retry - Handle transient failures.
5. Use CDN URLs - Leverage Vercel's global CDN.
6. Monitor usage - Track storage and bandwidth usage.