Start with a handler. This one accepts images and PDFs from signed-in users, gives each file a unique path, and saves a database record when it lands. `getUser` and `db` are your app's existing auth and database helpers:
```ts
// lib/uploads.ts
import "server-only"
import { BlobError, uploadHandler } from "@upstash/blob"
import { getUser } from "./auth"
import { db } from "./db"
export const uploads = uploadHandler({
constraints: { maxSize: "20mb", contentTypes: ["image/*", "application/pdf"] },
onBeforeUpload: async ({ request }) => {
const user = await getUser(request)
if (!user) throw new BlobError("unauthorized")
return {
path: `${user.id}/${crypto.randomUUID()}`,
metadata: { owner: user.id },
}
},
onUploadComplete: async ({ uploadId, path, url, metadata }) => {
await db.files.upsert({ uploadId, owner: metadata.owner, path, url })
// Sent to the client as upload.blob.data, with its type inferred end to end.
return { fileId: uploadId }
},
})
```
The row saved in `onUploadComplete` lets your database answer questions like "which files belong to this user?" The bucket holds the bytes; your database indexes the files.
In Next.js, mounting it takes two lines:
```ts
// app/api/upload/route.ts
import { uploads } from "@/lib/uploads"
export const { GET, POST } = uploads
```
Then connect your UI to the handler's type:
```tsx
"use client"
import { uploadHooks } from "@upstash/blob/react"
import type { uploads } from "@/lib/uploads"
const { useUpload } = uploadHooks{upload.error.message}
} {upload?.status === "done" &&Saved file {upload.blob.data.fileId}
} ) } ``` That `fileId` is inferred from `onUploadComplete`. Rename it on the server and TypeScript points to the component that needs updating. Add named routes and `useUpload("avatar")` only accepts names your handler defines. For uploads that need extra data, an [input schema](https://upstash.com/docs/blob/uploads/upload-handler#uploadroute) gives you both server validation and a typed `start({ file, input })` call. No duplicate request and response interfaces, code generation, or type assertions to keep the two sides in sync. The client imports only a type, so your server code stays on the server. The defaults do just as much work. The hook already knows to call `/api/upload`. Its `accept` value comes from your handler's allowed file types, and the server enforces your size and type constraints. Files over 16 MB automatically use multipart uploads, with pause, resume, retries for failed parts, and refreshed upload signatures when they expire. Small and large files expose the same progress and error state to your UI. You can change the defaults when your app needs it; the [upload client](https://upstash.com/docs/blob/uploads/upload-client) and [large-file docs](https://upstash.com/docs/blob/uploads/large-files) cover the controls. ## Direct uploads Your server authorizes the upload and gives the browser a signed URL. The browser sends the file bytes directly to Upstash, then your server verifies the upload and runs `onUploadComplete`. The file never passes through your server, so its request body limit does not restrict the upload.
You start with a short, typed integration that already handles the upload mechanics. Your code stays focused on your product as its file storage needs grow.
## Simple pricing, no extra CDN charges
**CDN delivery is included in our standard pricing.** On pay as you go, outbound bandwidth costs **$0.02 per GB** and reads cost **$0.30 per million**, with the same rates worldwide.
You pay the same rates whether a file comes from the CDN or the underlying storage, with no extra delivery fees.
Storage costs **$0.02 per GB** per month, and writes, lists and copies cost $4.50 per million. Uploads cost nothing to transfer, deletes are free, and storage is billed on the monthly average of the bucket rather than its peak. Every meter is billed as measured, with no rounding up to a whole unit.
The free tier is 1 GB of storage, 10 GB of bandwidth, 10,000 reads and 2,000 writes a month, with no card. The full breakdown is on the [pricing page](https://upstash.com/pricing/blob).
## Try it
Create a bucket in the [Upstash Console](https://console.upstash.com), copy the token, and the [quickstart](https://upstash.com/docs/blob/overall/quickstart) takes you to a working file picker. The [recipes](https://upstash.com/docs/blob/recipes/avatars) go further: avatars, attachments, private documents, exports and video, each wired end to end.
We would like to hear what you build with it, and what gets in your way. Find us on [Discord](https://upstash.com/discord).