Files that belong to the site rather than to a user: the images and brochures an editor uploads from an admin page, and the fonts, stylesheets and downloads your build ships. Nobody owns them, everybody reads them, and they should be cached for as long as possible.
Three choices make that work:
* **An editor-only upload route.** The role check runs in `onBeforeUpload`, before anything is signed.
* **A row per media file.** Path, URL, alt text and uploader live in your table. The bucket holds bytes, your database is the index.
* **A path that changes when the bytes do.** `uniquePath` for uploads, a versioned filename for build assets, so `cache: 'immutable'` is always honest.
This recipe uses a public bucket, since every one of these files is meant to be linked from a page. If you have not created one yet, start with the [Quickstart](/blob/overall/quickstart). If you only need the deploy script, skip to [Build-time assets](#build-time-assets).
***
## The media handler
Editors upload from the browser, so the bytes go straight to storage and your server only authorizes them.
```ts lib/uploads.ts theme={"system"}
import "server-only"
import { BlobError, uniquePath, uploadHandler } from "@upstash/blob"
import { getUser } from "./auth"
import { db } from "./db"
export const uploads = uploadHandler({
constraints: { contentTypes: ["image/*", "application/pdf"], maxSize: "25mb" },
onBeforeUpload: async ({ request, file }) => {
const user = await getUser(request)
if (!user) throw new BlobError("unauthorized")
if (user.role !== "editor") throw new BlobError("forbidden")
return {
path: uniquePath`media/${file.name}`,
cache: "immutable",
metadata: { uploader: user.id },
}
},
onUploadComplete: async ({ uploadId, path, url, file, metadata }) => {
try {
// The browser retries this request on a flaky network, so upsert on uploadId.
await db.media.upsert({
id: uploadId,
name: file.name,
alt: "",
path,
url,
uploaderId: metadata.uploader,
})
} catch (e) {
// A throw here deletes the object, so make it a deliberate refusal the user can retry from.
console.error("[uploads] could not record", path, e)
throw new BlobError("not_ready", { message: "could not save the file, try again" })
}
return { mediaId: uploadId, url }
},
})
```
`uniquePath` gives every upload its own object, so re-uploading a file called `hero.png` never replaces last month's `hero.png`. Because the path never repeats, `cache: 'immutable'` needs no invalidation at all.
A throw out of `onUploadComplete` deletes the object, so the `catch` turns a database failure into a refusal the user can retry from. `not_ready` is the 503 code, the one that means try again. See [Upload handler](/blob/uploads/upload-handler#onuploadcomplete) and [Errors](/blob/reference/errors#the-codes).
***
## The route
Mount the handler, then bind the hooks to it.
```ts app/api/upload/route.ts theme={"system"}
import { uploads } from "@/lib/uploads"
export const { GET, POST } = uploads
```
```ts lib/upload-hooks.ts theme={"system"}
"use client"
import { uploadHooks } from "@upstash/blob/react"
import type { uploads } from "./uploads"
export const { useUpload } = uploadHooks{upload.error.message}
} {upload?.status === "done" && ( )} ) } ``` ```ts app/actions.ts theme={"system"} "use server" import { getUser } from "@/lib/auth" import { db } from "@/lib/db" export async function setAltText(id: string, alt: string) { const user = await getUser() if (user?.role !== "editor") throw new Error("forbidden") await db.media.update({ id, alt }) } ``` The rendered page reads the row and never asks the bucket anything: ```tsx theme={"system"} const cover = await db.media.find({ id: post.coverMediaId })