Quickstart - Upstash Documentation

Upstash Blob is S3-compatible object storage. @upstash/blob has a Bucket client for your server, and an upload handler plus React hooks that upload from the browser straight to storage. This page builds a working file picker on Next.js App Router. Other frameworks work the same way; see Other frameworks.

Setup#

npm install @upstash/blob

Create a bucket in the Upstash Console and put its token in your environment.

.env

UPSTASH_BLOB_TOKEN=...

The console asks whether the bucket is public or private:

Public: every object has a public URL. For avatars, product images, anything a page links to directly.
Private: no public URL. Every read goes through a time-limited signed URL. For user documents, invoices, anything that must not be guessable.

Upload from your server#

lib/reports.ts

import { Bucket } from "@upstash/blob"const bucket = Bucket.fromEnv()export async function saveReport(file: Blob) {  const blob = await bucket.put("reports/2026-01.pdf", file, {    contentType: "application/pdf",  })  return blob.url}

Bytes already on your server go to the bucket with put. blob.url is the public object URL, undefined on a private bucket. See Writing.

Upload from the browser#

Files a user picks go straight from the browser to storage. Your server only authorizes the upload and records the result, so the bytes never pass through it.

Write the upload handler

lib/uploads.ts

import "server-only"import { uploadHandler } from "@upstash/blob"export const uploads = uploadHandler({  constraints: {    maxSize: "20mb",    contentTypes: ["image/*", "application/pdf"],  },  onBeforeUpload: ({ file }) => ({ path: `images/${file.name}` }),})

The handler runs on your server. It decides who may upload, where the object goes, and what happens once it lands. It never sees the bytes.

This one accepts anyone. Upload handler adds the auth check and the completion callback.

Mount it as a route

app/api/upload/route.ts

import { uploads } from "@/lib/uploads"export const { GET, POST } = uploads

POST runs the upload and GET serves the route's constraints. The hooks look at /api/upload by default, so nothing else has to name a URL.

Bind the hooks to the handler

lib/upload-hooks.ts

"use client"import { uploadHooks } from "@upstash/blob/react"import type { uploads } from "./uploads"export const { useUpload } = uploadHooks<typeof uploads>()

uploadHooks<typeof uploads>() reads the handler's type, so route names and completion data are checked at compile time. The import type is erased at build time and never pulls server code into the browser bundle.

Upload a file

app/page.tsx

"use client"import { useUpload } from "@/lib/upload-hooks"export default function Page() {  const { start, upload, accept } = useUpload()  return (    <div>      <input        type="file"        accept={accept}        onChange={(e) => start({ file: e.target.files?.[0] })}      />      {upload && <p>{upload.status}</p>}      {upload?.pending && <progress value={upload.percent} max={100} />}      {upload?.status === "done" && (        <a href={upload.blob.url}>{upload.blob.path}</a>      )}      {upload?.status === "error" && <p>{upload.error.message}</p>}    </div>  )}

You get these without more code:

Multipart for large files. Past 16 MB the SDK switches to parts, with pause, resume and per-part retry. See Large files.
Retries. Failed parts back off and retry, and an expired signature is refreshed mid-upload.
A picker that matches the server. accept comes from the route's own GET, so an oversized file is refused before any request goes out. See Constraints.
Progress. percent, status and pending read the same for one PUT or 200 parts.
Types end to end. Whatever onUploadComplete returns is upload.blob.data on the client.

Next steps#

Upload handler

Auth, routes, and the completion callback in full.

Upload client

useUpload, the record it renders, and the non-React client.

Writing

put, metadata, conditional writes and multipart from the server.

Recipes

Avatars, attachments and private documents, wired end to end.