HyperFrames on Vercel

HyperFrames on Vercel

Preview HTML-based video compositions in the browser and render MP4s server-side — on Vercel. Powered by Vercel Sandbox for rendering and Vercel Blob for output storage.

HyperFrames is an open-source video rendering framework: write HTML + CSS + GSAP, get a reproducible MP4.

Live demo: hyperframes-on-vercel.vercel.app

Deploy

Deploying provisions a Vercel Blob store; BLOB_READ_WRITE_TOKEN is injected automatically. Sandbox auth is handled at runtime via VERCEL_OIDC_TOKEN — no extra setup.

What this template does

• Preview a bundled composition (vercel-intro) in the browser using <hyperframes-player>, the zero-dependency web component from @hyperframes/player.
• Render the composition to an MP4 by POSTing to /api/render. The route restores a pre-baked Vercel Sandbox, runs hyperframes render, uploads the MP4 to Vercel Blob, and returns a public URL.

Authoring happens locally. This template ships with one pre-authored composition. To build your own, use the HyperFrames CLI on your machine:

1
npx hyperframes init my-video
2
cd my-video
3
npx hyperframes preview   # live-reload editor in your browser

Then swap it into this template (see Swapping the composition below).

Architecture

1
Browser                   Vercel Functions (node)         Vercel Sandbox (Firecracker microVM)
2
┌──────────────────┐      ┌────────────────────────┐      ┌──────────────────────────────────┐
3
│ <hyperframes-    │ ───▶ │ /api/render            │ ──▶  │ (restored from snapshot, or      │
4
│  player>         │      │  - read composition    │      │  freshly provisioned in dev)     │
5
│ preview iframe   │      │  - writeFiles to sbox  │      │                                  │
6
│                  │      │  - runCommand: render  │      │  hyperframes render composition  │
7
│                  │ ◀──  │  - readFileToBuffer    │ ◀──  │    (Chromium + ffmpeg-static)    │
8
│                  │ url  │  - put() → Vercel Blob │  mp4 │                                  │
9
└──────────────────┘      └────────────────────────┘      └──────────────────────────────────┘

The build-time snapshot

Cold render of the bundled ~11s composition is roughly 2 minutes. Most of that time is the actual Chromium render — not setup — because we pre-bake a sandbox snapshot at build time instead of installing dependencies on every request.

scripts/create-snapshot.ts runs as part of next build:

1. Spin up a fresh node22 sandbox
2. dnf install Chromium system libraries (nss, libXcomposite, pango, …)
3. npm install hyperframes ffmpeg-static ffprobe-static
4. Symlink ffmpeg-static/ffmpeg and ffprobe-static/bin/linux/x64/ffprobe into /usr/local/bin/
5. npx hyperframes browser ensure to download chrome-headless-shell
6. sandbox.snapshot({ expiration: 7 days }) and write the snapshot ID to a pointer blob at snapshot-cache/<deployment_id>.json

At render time, lib/sandbox.ts' restoreOrCreate reads the pointer blob, restores a sandbox from the snapshot in ~100 ms, writes the composition files, and runs hyperframes render. In non-production (local vercel dev) it falls back to a fresh setup automatically.

Why Vercel Sandbox (and not a regular serverless function)

Vercel Functions cap at 300s and 50 MB compressed bundle — HyperFrames needs a full Chromium + FFmpeg at runtime, which busts the bundle limit. Vercel Sandbox is the purpose-built primitive for this workload: an Amazon Linux 2023 Firecracker microVM with sudo-level package installs, up to 5 hours of runtime, and up to 8 vCPUs (we use 4).

With 4 vCPUs, hyperframes render --workers auto launches 3 parallel Chrome workers, cutting the render time roughly 2× vs. the single-worker default.

Local development

1
npm install
2
npm run dev

Browser preview works locally out of the box. The /api/render route needs Vercel Sandbox auth — run vercel env pull .env.local after linking the project to get VERCEL_OIDC_TOKEN locally, or use vercel dev.

Project structure

1
app/
2
  api/render/route.ts    # POST → restore sandbox, render, upload to Blob
3
  page.tsx               # Preview + "Render" button
4
  layout.tsx
5
  globals.css
6
lib/
7
  sandbox.ts             # Snapshot-aware wrapper around @vercel/sandbox
8
scripts/
9
  create-snapshot.ts     # Build-time: pre-bake the sandbox snapshot
10
public/
11
  compositions/
12
    vercel-intro/        # The bundled example composition
13
      index.html
14
      assets/

Swapping the composition

1. Drop your composition bundle into public/compositions/<your-name>/.
2. Update PREVIEW_COMPOSITION_DIR at the top of lib/preview.ts (used by both preview and render).
3. Optionally update COMPOSITION_WIDTH / COMPOSITION_HEIGHT at the top of app/page.tsx to match your composition's dimensions.

Pricing

Vercel Sandbox pricing — Pro plans include $20/mo in Sandbox credit. At ~2 minutes per render on 4 vCPUs, that covers roughly 100 renders/month of the bundled ~11-second example. Snapshot storage (the ~1.1 GB snapshot per deployment) is included in Sandbox pricing.

License

Apache-2.0 — same license as HyperFrames itself.

Links

• HyperFrames repo
• HyperFrames docs
• Vercel Sandbox docs
• Vercel Blob docs