Video Uploads - Upstash Documentation

Course lessons, screen recordings, a creator upload form: files of a few hundred megabytes to a few gigabytes, picked in the browser and played back on a page. Three choices make that work:

multipart: true. Every video goes up in parts, whatever it weighs, which is what buys pause, resume and per-part retry on a two hour upload.
A unique path, cached forever. uniquePath plus cache: 'immutable' is one object per video, never overwritten, so its URL can be cached for a year.
A row per video. Written as pending before the bytes and flipped to ready after them, so a page never links a file that is only half there.

The bytes go from the browser straight to storage. Your server authorizes the upload and records what landed, and never carries a gigabyte through a function. This recipe uses a public bucket. If you have not created one yet, start with the Quickstart.

The handler

Unlike the other recipes, the row is written in onBeforeUpload, before a byte exists, and marked pending. A tab that dies halfway leaves a row still saying pending, which is what a cron can find and sweep. onUploadComplete only flips it to ready.

lib/uploads.ts

import "server-only"
import * as z from "zod"
import { BlobError, uniquePath, uploadHandler, uploadRoute } from "@upstash/blob"
import { getUser } from "./auth"
import { db } from "./db"

const video = uploadRoute()({
  constraints: { contentTypes: ["video/*"], maxSize: "5gb" },
  multipart: true,
  input: z.object({ title: z.string().min(1) }),

  onBeforeUpload: async ({ request, input, file }) => {
    const user = await getUser(request)
    if (!user) throw new BlobError("unauthorized")

    const videoId = crypto.randomUUID()
    const path = uniquePath`videos/${user.id}/${file.name}`

    await db.videos.insert({
      id: videoId,
      ownerId: user.id,
      title: input.title,
      path,
      status: "pending",
    })

    return { path, cache: "immutable", state: { videoId } }
  },

  onUploadComplete: async ({ state, path, url, size }) => {
    try {
      // Last. The row stops looking abandoned only once everything else is written.
      await db.videos.update(state.videoId, { url, size, status: "ready" })
    } 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 video, try again" })
    }
    return { videoId: state.videoId }
  },
})

export const uploads = uploadHandler({ routes: { video } })

onBeforeUpload runs once per upload, so one upload is one row, and the row is the placeholder the rest of the app renders while the upload runs. A resume does not run it again: if the tab closes and the user picks the same file later, the SDK sends only the missing parts, and onUploadComplete flips the row that already exists. multipart: true also means nothing is stored at the path until the upload completes. A tab that dies halfway leaves parts, which abortStaleMultipartUploads() on a cron clears, and a row still pending, which the same cron deletes once the parts are gone. See Abandoned uploads. 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 and Errors.

The route

app/api/upload/route.ts

import { uploads } from "@/lib/uploads"

export const { GET, POST } = uploads

lib/upload-hooks.ts

"use client"

import { uploadHooks } from "@upstash/blob/react"
import type { uploads } from "./uploads"

export const { useUpload } = uploadHooks<typeof uploads>()

The upload component

A gigabyte takes minutes, so the controls matter more than they do for a picture.

components/video-upload.tsx

"use client"

import { useUpload } from "@/lib/upload-hooks"

export function VideoUpload({ title }: { title: string }) {
  const { start, upload, accept } = useUpload("video")

  return (
    <>
      <input
        type="file"
        accept={accept}
        onChange={(e) => start({ file: e.target.files?.[0], input: { title } })}
      />

      {upload?.pending && <progress value={upload.percent} max={100} />}
      {upload?.status === "finishing" && <p>Finishing up...</p>}
      {upload?.stalled && <p>Connection is struggling, retrying...</p>}

      {upload?.canPause && upload.status === "uploading" && (
        <button onClick={() => upload.pause()}>Pause</button>
      )}
      {upload?.status === "paused" && <button onClick={() => upload.resume()}>Resume</button>}
      {upload?.pending && <button onClick={() => upload.cancel()}>Cancel</button>}

      {upload?.status === "error" && (
        <button onClick={() => upload.retry()}>{upload.error.message}</button>
      )}
    </>
  )
}

canPause is true throughout because the route sets multipart: true. percent sits at 99 while onUploadComplete runs, which is why finishing gets its own line rather than a bar that looks stuck. If the tab is closed and the user picks the same file again later, the upload resumes from the parts that landed, with no API to call. Large files covers all of that.

Playing it back

Render the URL from your own row, and let status keep half-uploaded videos off the page.

components/video-player.tsx

import { db } from "@/lib/db"

export async function VideoPlayer({ id }: { id: string }) {
  const video = await db.videos.find({ id, status: "ready" })
  if (!video) return <p>Still processing...</p>

  return <video controls src={video.url} width={720} />
}

url is the public object URL, so the browser fetches the file directly and nothing streams through your app. The object is stored once and never overwritten, which is what makes cache: 'immutable' correct here: there is no stale version to worry about, and every play after the first can be served from cache. For videos that must not be watchable by anyone holding the link, use a private bucket and sign each play with signedReadUrl, asking for an expiresIn comfortably longer than the video runs. See Private documents for that shape.

Deleting

Delete the row first, then the object. The page stops linking the video immediately, and if the second step fails the leftover is an object nobody links to rather than a player pointing at a 404. del treats an already missing object as success, so it is safe to retry.

app/actions.ts

"use server"

import { Bucket } from "@upstash/blob"
import { getUser } from "@/lib/auth"
import { db } from "@/lib/db"

const bucket = Bucket.fromEnv()

export async function deleteVideo(id: string) {
  const user = await getUser()
  const video = await db.videos.find({ id, ownerId: user?.id })
  if (!video) throw new Error("not found")

  await db.videos.delete(id)
  await bucket.del(video.path)
}

Closing an account is the same thing in bulk. The rows are the only thing that knows the paths, so read them first, delete the objects, then drop the rows. If it fails partway, run it again:

const videos = await db.videos.findMany({ ownerId: user.id })
await bucket.del(videos.map((v) => v.path))
await db.videos.deleteMany({ ownerId: user.id })

Next steps

Large files

Parts, pause, resume, retries, and where the threshold sits.

Abandoned uploads

The pending row, and the cron that sweeps what never finished.

Constraints

What video/* expands to, and how maxSize is read.

Caching

immutable, revalidate, and what a private bucket stores instead.

​The handler

​The route

​The upload component

​Playing it back

​Deleting

​Next steps