Next.js boilerplate with Vercel Blob

Access mode is fixed at creation

• A store is private or public, forever. BLOB_ACCESS in src/lib/storage/access.ts must match it. Every put() and upload() names the mode, and a mismatch fails.
• User files go in a private store. Reads use getSignedDownloadUrl(), a presigned GET that expires in 15 minutes by default.
• Public stores are for things that are public by nature. The URL never expires and the pathname is the only secret.
• Need both? Two stores. Never try to mix them in one.

Credentials

• BLOB_READ_WRITE_TOKEN is required. handleUpload() signs client tokens with it. It can read, overwrite and delete every blob: server-side only, never NEXT_PUBLIC_.
• On Vercel the SDK also gets OIDC credentials and prefers them for server reads and writes. Do not pass token to put(), del() or get() unless you mean to bypass OIDC.
• src/lib/storage/index.ts starts with import "server-only". Keep it. The dropzone may import only access.ts, keys.ts and report.ts.
• Never read an env var at module scope. next build runs with none set.

Treat blobs as immutable

• Overwrites and deletes take up to 60 seconds to leave the CDN cache, and browsers keep their own copy for cacheControlMaxAge (one month by default).
• New content means a new pathname. Store the new key, delete the old blob.
• useCache: false on get() reads from origin, but costs Fast Origin Transfer on every call. Only for data that must be fresh.

Costs to keep in mind

• put, copy and list are advanced operations, the priciest line. Never list() on a request path. Keep keys in your database instead.
• Browsing the store in the Vercel dashboard counts as operations too.
• del() is free but counts toward the rate limit (per blob, not per call).
• issueSignedToken() is a network call. getSignedDownloadUrl() caches one store-wide read token and signs URLs locally. Keep it that way.
• Serving a private blob through a function pays twice: Blob transfer into the function, Fast Data Transfer out. Prefer the presigned URL.

Deleting

• Prove ownership first. These credentials can delete anything.
• Delete the blob, then the row. An orphaned blob costs storage. An orphaned row breaks a page.
• deleteObject() treats "already gone" as success, so cleanup jobs can retry.

A client token is a write credential

Whoever holds one can write to your store until it expires. No session, no cookie, no further check.

• Every path that issues a token calls requireUploader(request) from @/lib/storage/authorize first. In onBeforeGenerateToken, it is the first line. Nothing after it runs for an anonymous or cross-origin caller.
• Throw to refuse. handleUpload() issues no token when onBeforeGenerateToken throws. Returning {} issues an unrestricted one.
• Keep validUntil short. The route uses 15 minutes. The SDK default is an hour.
• Never log a token or a signed URL. Never put one in an analytics property or an error report. Responses carry cache-control: no-store.

Never trust the pathname from the client

upload(pathname, ...) lets the browser name the pathname. The token is bound to it, and the server can only accept or refuse it.

• The server mints keys: objectKey({ ownerId: uploader.id, ... }) in the reserve step of src/app/api/upload/route.ts. The owner id comes from the session, never from the request body.
• In onBeforeGenerateToken, call assertUploadPathname(pathname, uploader.id, contentType) before anything else is returned. It checks the owner segment, the exact key shape and the extension.
• Do not "fix up" a bad pathname. Refuse it. A token for a rewritten pathname does not exist; the SDK signs the one the client sent.
• Before a read or a delete of a key that came from a request, call isOwnedBy(key, uploader.id). Authentication is not authorisation.

Allowlist types and sizes in the token

• allowedContentTypes gets exactly one entry: the claimed type, already checked against ALLOWED_CONTENT_TYPES in src/lib/storage/keys.ts.
• maximumSizeInBytes gets the claimed size, already checked against MAX_UPLOAD_BYTES. Blob enforces both at the store, so a client that lied fails there.
• Allowlist, never blocklist. SVG stays out: it runs script when served inline.
• Change a limit in keys.ts, not in the route. The dropzone reads the same constants.

Overwrites and suffixes

• allowOverwrite: false and addRandomSuffix: false, always, in the upload route. The key already holds a uuid. A suffix changes the pathname the browser expects. An overwrite lets a leaked token replace a file.
• Need a new version of a file? New key. Then delete the old one.

User files never go through a function

• Vercel Functions cap the request body at 4.5 MB, bill every second of the transfer, and add Fast Data Transfer to every byte. Client uploads have none of that.
• putObject() is for bytes your own code makes: exports, thumbnails, PDFs. Never for a file a user is sending.
• Never expose a storage helper as a server action that takes a key without an ownership check. A server action is a public endpoint.

onUploadCompleted

• It is a webhook from Vercel to your deployment. It does not fire on localhost unless VERCEL_BLOB_CALLBACK_URL points at a tunnel.
• handleUpload() verifies its signature with BLOB_READ_WRITE_TOKEN. Do not run requireUploader() on it: the caller is Vercel, and it sends no Origin.
• Make it idempotent. A non-2xx answer makes Vercel retry.
• Trust tokenPayload, which the server signed. Never trust clientPayload beyond the checks in onBeforeGenerateToken.