Connecting

This page covers creating the Bucket client, the options it takes, and running it on platforms without process.env.

import { Bucket } from "@upstash/blob"export const bucket = Bucket.fromEnv() // reads UPSTASH_BLOB_TOKEN

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

UPSTASH_BLOB_TOKEN=...

The token is a bearer secret. Anything holding it can read and write the whole bucket. Keep it server side, never in NEXT_PUBLIC_, VITE_, or any other variable your bundler inlines into client code.

Options#

import { Bucket } from "@upstash/blob"export const bucket = new Bucket({  token: process.env.UPSTASH_BLOB_TOKEN!,  cache: "immutable",  enableTelemetry: false,})

Bucket.fromEnv() is the same constructor with token read from UPSTASH_BLOB_TOKEN. It takes the same options minus the token, and a variable name when the token lives somewhere else:

Bucket.fromEnv({ cache: "immutable" })Bucket.fromEnv("REPORTS_BUCKET_TOKEN", { cache: "immutable" })

Whether the bucket is public or private is a console setting, not an option: the SDK learns it from the backend on the first request. See Private buckets.

Constructing a Bucket per request is fine. Credentials are cached per token, so two clients built from the same token share one.

Cloudflare Workers#

There is no process.env on Workers, so Bucket.fromEnv() throws. Pass the token from the request's env:

import { Bucket } from "@upstash/blob"export default {  async fetch(request: Request, env: { UPSTASH_BLOB_TOKEN: string }) {    const bucket = new Bucket({ token: env.UPSTASH_BLOB_TOKEN })    await bucket.put("hits.txt", "1")    return new Response("ok")  },}

An upload handler on Workers needs the same thing: build the bucket from env and pass it as bucket:.

Telemetry#

The SDK sends its version, runtime and platform as headers on credential requests to Upstash. Turn it off with UPSTASH_DISABLE_TELEMETRY in the environment (any value), or enableTelemetry: false on the Bucket.

Using an S3 client#

import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3"import { bucket } from "@/lib/blob"const { endpoint, region, bucket: name, credentials } = bucket.s3()const s3 = new S3Client({ endpoint, region, credentials })await s3.send(  new GetObjectCommand({ Bucket: name, Key: "reports/q3.pdf", Range: "bytes=0-1023" }),)

Buckets are backed by Cloudflare R2 and are S3-compatible. bucket.s3() returns a config for @aws-sdk/client-s3, for anything the SDK does not wrap: byte ranges, conditional GETs, delimiters and common prefixes, object tagging.

endpoint and credentials are async providers rather than values. Pass them through as they come, so the aws-sdk can pick up a fresh credential when the old one expires.

An error message that mentions R2 is talking about the storage layer.

Next steps#