Storage Updates & Release Notes

Minor Changes

c4976ba: Add rename(fromUrlOrPathname, toPathname, options) to move a blob to another pathname. The blob is copied to the new pathname and the source is deleted afterwards; if the copy fails the source is left untouched. By default renaming onto an existing blob throws — pass allowOverwrite: true to replace it, or addRandomSuffix: true to generate a unique destination. Requires a read-write token (client tokens are not supported).

89d94e9: Restore the useCache option on get(). Passing useCache: false bypasses the CDN cache and serves the blob directly from origin storage (via the cache=0 query parameter), guaranteeing the latest content at the cost of slower reads. Defaults to true.

Minor Changes

31a8b8f: Deprecate the useCache option on get(). The backend no longer honors the cache=0 query parameter it produced, so the option is now a no-op — reads always go through the standard caching path. The option is still accepted (and ignored) to avoid breaking existing callers, and will be removed in a future major version.

Patch Changes

9ac2586: Read the Vercel OIDC token via @vercel/oidc's refreshing getVercelOidcToken instead of the non-refreshing getVercelOidcTokenSync. This refreshes an expired token in development environments. In production with a valid token, behavior is unchanged. If a refresh is needed but fails, the token is treated as absent so callers still fall back to BLOB_READ_WRITE_TOKEN.

Patch Changes

• c9d9a1a: Apply ifMatch/allowOverwrite validation to handleUpload and generateClientTokenFromReadWriteToken. When ifMatch is set via onBeforeGenerateToken or direct token generation, allowOverwrite is now implicitly enabled. Explicitly passing allowOverwrite: false with ifMatch throws a clear error.
• 6dcecb8: Make ifMatch imply allowOverwrite: true on put(). Previously, using ifMatch without explicitly setting allowOverwrite: true would cause the server to send conflicting conditional headers to S3, resulting in 500 errors. Now the SDK implicitly enables allowOverwrite when ifMatch is set, and throws a clear error if allowOverwrite: false is explicitly combined with ifMatch.

Minor Changes

04ca1f0: Add private storage support (beta), a new get() method, and conditional gets

Private storage (beta)

You can now upload and read private blobs by setting access: 'private' on put() and get(). Private blobs require authentication to access — they are not publicly accessible via their URL.

New get() method

Fetch blob content by URL or pathname. Returns a ReadableStream along with blob metadata (url, pathname, contentType, size, etag, etc.).

Conditional gets with ifNoneMatch

Pass an ifNoneMatch option to get() with a previously received ETag. When the blob hasn't changed, the response returns statusCode: 304 with stream: null, avoiding unnecessary re-downloads.

Example

import { put, get } from "@vercel/blob";
// Upload a private blob
const blob = await put("user123/avatar.png", file, { access: "private" });
// Read it back
const response = await get(blob.pathname, { access: "private" });
// response.stream — ReadableStream of the blob content
// response.blob — metadata (url, pathname, contentType, size, etag, ...)
// Conditional get — skip download if unchanged
const cached = await get(blob.pathname, {
  access: "private",
  ifNoneMatch: response.blob.etag,
});
if (cached.statusCode === 304) {
  // Blob hasn't changed, reuse previous data
}

Learn more: https://vercel.com/docs/vercel-blob/private-storage

Minor Changes

6c68442: Add ETag support for conditional writes (optimistic concurrency control)
Return etag in all blob responses (put, copy, head, list, multipart)
Accept ifMatch option in put/copy/createMultipartUpload for conditional writes
Add BlobPreconditionFailedError for ETag mismatch (HTTP 412)

Usage Example: Preventing Lost Updates

When multiple users or processes might update the same blob concurrently, use ifMatch to ensure you don't overwrite someone else's changes:

import { put, head, BlobPreconditionFailedError } from "@vercel/blob";
// User 1: Read the current blob and get its ETag
const metadata = await head("config.json");
console.log(metadata.etag); // e.g., '"abc123"'
// User 2: Also reads the same blob (same ETag)
const metadata2 = await head("config.json");
// User 1: Updates the blob with ifMatch
// This succeeds because the ETag matches
const result1 = await put(
  "config.json",
  JSON.stringify({ setting: "user1" }),
  {
    access: "public",
    allowOverwrite: true, // Required when updating existing blobs
    ifMatch: metadata.etag, // Only write if ETag still matches
  }
);
console.log(result1.etag); // New ETag: '"def456"'
// User 2: Tries to update with their (now stale) ETag
// This fails because User 1 already changed the blob
try {
  await put("config.json", JSON.stringify({ setting: "user2" }), {
    access: "public",
    allowOverwrite: true,
    ifMatch: metadata2.etag, // Stale ETag - blob was modified!
  });
} catch (error) {
  if (error instanceof BlobPreconditionFailedError) {
    // The blob was modified since we last read it
    // Re-fetch, merge changes, and retry
    const freshMetadata = await head("config.json");
    await put("config.json", JSON.stringify({ setting: "user2" }), {
      access: "public",
      allowOverwrite: true,
      ifMatch: freshMetadata.etag, // Use fresh ETag
    });
  }
}

Key Points

• allowOverwrite: true: Required when updating an existing blob at the same path
• ifMatch: Only performs the write if the blob's current ETag matches this value
• Combined: "Overwrite, but only if the blob hasn't changed since I last read it"
• ETags follow RFC 7232 format with surrounding quotes (e.g., "abc123")

Major Changes

0b8ead9: BREAKING CHANGE:
To continue receiving onUploadCompleted callback once a file is uploaded with Client Uploads when not hosted on Vercel, you need to provide the callbackUrl at the onBeforeGenerateToken step when using handleUpload.
When hosted on Vercel:
No code changes required. The callbackUrl is inferred from Vercel system environment variables:
In preview environment: VERCEL_BRANCH_URL when available, otherwise VERCEL_URL
In production environment: VERCEL_PROJECT_PRODUCTION_URL
If you're not hosted on Vercel or you're not using Vercel system environment variables, your will need to provide the callbackUrl:
Before:

await handleUpload({
  body,
  request,
  onBeforeGenerateToken: async (pathname) => {
    /* options */
  },
  onUploadCompleted: async ({ blob, tokenPayload }) => {
    /* code */
  },
});

After:

await handleUpload({
  body,
  request,
  onBeforeGenerateToken: async (pathname) => {
    return { callbackUrl: 'https://example.com' }; // the path to call will be automatically computed
  },
  onUploadCompleted: async ({ blob, tokenPayload }) => {
    /* code */
  },
});

For local development:
Set the VERCEL_BLOB_CALLBACK_URL environment variable to your tunnel URL:
VERCEL_BLOB_CALLBACK_URL=https://abc123.ngrok-free.app
See the updated documentation at https://vercel.com/docs/vercel-blob/client-upload to know more.
Details:
Before this commit, during Client Uploads, we would infer the callbackUrl at the client side level (browser) based on location.href (for convenience).
This is wrong and allows browsers to redirect the onUploadCompleted callback to a different website.
While not a security risk, because the blob urls are already public and the browser knows them, it still pose a risk of database drift if you're relying on onUploadCompleted callback to update any system on your side.