upstash-blob-js

@upstash/blob SDK

S3-compatible object storage. Bucket runs on your server; uploadHandler plus React hooks upload from the browser straight to storage so the bytes never pass through your app.

Bundled docs and source

The @upstash/blob npm package includes docs in node_modules/@upstash/blob/docs/ and readable TypeScript source in node_modules/@upstash/blob/src/. Before writing or debugging SDK code, read and search the relevant docs and source.

Install & Setup

npm install @upstash/blob

Create a bucket in the console and set UPSTASH_BLOB_TOKEN. The token is a bearer secret for the whole bucket — keep it server side, never in NEXT_PUBLIC_ or any bundler-inlined variable.

A bucket is public (every object has a URL) or private (no URL; reads go through signedReadUrl). That is a console setting, not a client option — the SDK learns it from the backend.

import { Bucket } from "@upstash/blob"
 
export const bucket =

Writing

Bodies: Request, Blob/File, ArrayBuffer, typed array, string, ReadableStream. A stream carries no length — pass size (exact, streams through) or maxSize (buffers up to the cap), or put throws length_required.

Sizes are decimal: '20mb' is 20,000,000 bytes. '5mib' throws.

Use uniquePath for any value you don't control. Each ${} becomes one slugged filename that can never add a directory, and the finished path gets a random suffix — so two uploads of photo.png never collide. The literal parts of the template are passed through as written, so keep . and .. out of them yourself: a path with those segments is refused later, by the call that uses it, with a TypeError rather than a BlobError.

bucket.copy(from, to, { contentType, cache, metadata }) and bucket.move(from, to, options) preserve source properties you omit. bucket.updateJson(path, fn, { maxAttempts: 6 }) retries a read-modify-write on conflict with backoff.

Reading

get/info throw not_found. Nothing is buffered — wrap the stream to read it:

list pages with page.cursor (set only while more remains) and carries no contentType or metadata. prefix is the only filter — keep your own table as the index and treat the bucket as storage, not a queryable store.

Cache the link until expiresAt, never a deadline you compute — a link cannot outlive the credential that signed it, so you may get less than you asked for. await bucket.publicUrl(path) returns the public URL, undefined on a private bucket.

Deleting

Already-gone counts as success, so deletes are safe to retry. An array or prefix delete where objects survive throws partial_delete with them in e.failed. del({ prefix: '' }) is refused unless you pass all: true.

Browser uploads

The handler authorizes and records; the bytes go browser → storage, so platform request body caps don't apply. Supply your application's getUser and db.files.upsert implementations below.

GET serves the route's constraints, so accept fills the file dialog and an oversized file is refused before any request leaves the browser. uploadHooks<typeof uploads>() types route names and completion data at compile time; import type keeps server code out of the bundle.

This example assumes a public bucket. On a private one url is undefined, so store path instead and hand the client a bucket.signedReadUrl(path) when it needs to read.

Two rules that bite:

• onUploadComplete can run more than once. The browser retries it, so upsert on uploadId rather than inserting.
• A throw out of onUploadComplete deletes the object. That is right for a refusal and wrong for a transient database error — catch your own storage errors.

Files over 16 MB go up in parts, which is what gives pause(), resume(), per-part retry, and resume-after-reload when the user picks the same file again. percent caps at 99 until status is done; drive UI off upload.pending.

Use multipart: true on the handler to make every upload multipart. Then a closed tab leaves incomplete parts rather than a stored object nobody recorded, and one cron cleans up:

For routes where the bytes must pass through your app, write an ordinary route calling bucket.put and drive it with useServerUpload from @upstash/blob/react.

Caching

cache is written once, at upload, and stored with the object — changing it means writing the object again.

immutable needs a path that changes when the bytes do — either uniquePath per upload, or a stable path served through versionedUrl. On a private bucket private replaces public.

Errors

Use BlobError.is(), never instanceof — an ESM and a CJS copy are different classes. Codes: not_found, already_exists, conflict, content_type_not_allowed, invalid_input, too_large, empty_body, length_required, signature_mismatch, unauthorized, forbidden, rate_limited, not_ready, partial_delete, move_left_a_copy, invalid_content_type_pattern, mint_backoff, request_failed.

A refusal keeps its code all the way to the browser, so hooks switch on error.code rather than status numbers. Bad option values ('5mib', a missing token) throw a TypeError where they are written, not a BlobError per request.

S3 clients

Buckets are S3-compatible. Use this for what the SDK doesn't wrap — byte ranges, conditional GETs, tagging. Pass the providers through as they come so the AWS SDK can refresh an expired credential.