{"id":51442996,"url":"https://github.com/heygen-com/hyperframes-vercel-template","last_synced_at":"2026-07-05T13:30:38.797Z","repository":{"id":354705700,"uuid":"1216417687","full_name":"heygen-com/hyperframes-vercel-template","owner":"heygen-com","description":"Next.js template for HyperFrames — preview HTML video compositions and render MP4s on Vercel Sandbox","archived":false,"fork":false,"pushed_at":"2026-05-07T18:02:18.000Z","size":8778,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-07T19:36:38.080Z","etag":null,"topics":["ffmpeg","gsap","hyperframes","mp4","nextjs","puppeteer","template","vercel","vercel-sandbox","vercel-template","video","video-rendering"],"latest_commit_sha":null,"homepage":"https://hyperframes.heygen.com","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heygen-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T22:12:04.000Z","updated_at":"2026-05-07T18:02:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heygen-com/hyperframes-vercel-template","commit_stats":null,"previous_names":["heygen-com/hyperframes-vercel-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/heygen-com/hyperframes-vercel-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fhyperframes-vercel-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fhyperframes-vercel-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fhyperframes-vercel-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fhyperframes-vercel-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heygen-com","download_url":"https://codeload.github.com/heygen-com/hyperframes-vercel-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heygen-com%2Fhyperframes-vercel-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35156494,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","gsap","hyperframes","mp4","nextjs","puppeteer","template","vercel","vercel-sandbox","vercel-template","video","video-rendering"],"created_at":"2026-07-05T13:30:38.059Z","updated_at":"2026-07-05T13:30:38.790Z","avatar_url":"https://github.com/heygen-com.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperFrames on Vercel\n\nPreview HTML-based video compositions in the browser and render MP4s server-side — on Vercel. Powered by [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) for rendering and [Vercel Blob](https://vercel.com/docs/vercel-blob) for output storage.\n\n[HyperFrames](https://github.com/heygen-com/hyperframes) is an open-source video rendering framework: write HTML + CSS + GSAP, get a reproducible MP4.\n\n![Template preview showing the Vercel intro composition playing in the browser](./docs/preview.png)\n\n**Live demo:** [hyperframes-on-vercel.vercel.app](https://hyperframes-on-vercel.vercel.app)\n\n## Deploy\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?demo-title=HyperFrames+on+Vercel\u0026demo-description=Preview+HTML+video+compositions+in+the+browser+and+render+MP4s+server-side+on+Vercel+Sandbox.\u0026demo-image=https%3A%2F%2Fraw.githubusercontent.com%2Fheygen-com%2Fhyperframes-vercel-template%2Fmain%2Fdocs%2Fpreview.png\u0026demo-url=https%3A%2F%2Fhyperframes-on-vercel.vercel.app\u0026from=templates\u0026project-name=hyperframes-on-vercel\u0026repository-name=hyperframes-on-vercel\u0026repository-url=https%3A%2F%2Fgithub.com%2Fheygen-com%2Fhyperframes-vercel-template\u0026stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D)\n\nDeploying 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.\n\n## What this template does\n\n- **Preview** a bundled composition (`vercel-intro`) in the browser using `\u003chyperframes-player\u003e`, the zero-dependency web component from `@hyperframes/player`.\n- **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.\n\n**Authoring happens locally.** This template ships with one pre-authored composition. To build your own, use the HyperFrames CLI on your machine:\n\n```bash\nnpx hyperframes init my-video\ncd my-video\nnpx hyperframes preview   # live-reload editor in your browser\n```\n\nThen swap it into this template (see [Swapping the composition](#swapping-the-composition) below).\n\n## Architecture\n\n```\n Browser                   Vercel Functions (node)         Vercel Sandbox (Firecracker microVM)\n┌──────────────────┐      ┌────────────────────────┐      ┌──────────────────────────────────┐\n│ \u003chyperframes-    │ ───▶ │ /api/render            │ ──▶  │ (restored from snapshot, or      │\n│  player\u003e         │      │  - read composition    │      │  freshly provisioned in dev)     │\n│ preview iframe   │      │  - writeFiles to sbox  │      │                                  │\n│                  │      │  - runCommand: render  │      │  hyperframes render composition  │\n│                  │ ◀──  │  - readFileToBuffer    │ ◀──  │    (Chromium + ffmpeg-static)    │\n│                  │ url  │  - put() → Vercel Blob │  mp4 │                                  │\n└──────────────────┘      └────────────────────────┘      └──────────────────────────────────┘\n```\n\n### The build-time snapshot\n\nCold 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.\n\n`scripts/create-snapshot.ts` runs as part of `next build`:\n\n1. Spin up a fresh `node22` sandbox\n2. `dnf install` Chromium system libraries (`nss`, `libXcomposite`, `pango`, …)\n3. `npm install hyperframes ffmpeg-static ffprobe-static`\n4. Symlink `ffmpeg-static/ffmpeg` and `ffprobe-static/bin/linux/x64/ffprobe` into `/usr/local/bin/`\n5. `npx hyperframes browser ensure` to download chrome-headless-shell\n6. `sandbox.snapshot({ expiration: 7 days })` and write the snapshot ID to a pointer blob at `snapshot-cache/\u003cdeployment_id\u003e.json`\n\nAt 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.\n\n### Why Vercel Sandbox (and not a regular serverless function)\n\nVercel Functions cap at 300s and 50 MB compressed bundle — HyperFrames needs a full Chromium + FFmpeg at runtime, which busts the bundle limit. [Vercel Sandbox](https://vercel.com/docs/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).\n\nWith 4 vCPUs, `hyperframes render --workers auto` launches 3 parallel Chrome workers, cutting the render time roughly 2× vs. the single-worker default.\n\n## Local development\n\n```bash\nnpm install\nnpm run dev\n```\n\nBrowser 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`.\n\n## Project structure\n\n```\napp/\n  api/render/route.ts    # POST → restore sandbox, render, upload to Blob\n  page.tsx               # Preview + \"Render\" button\n  layout.tsx\n  globals.css\nlib/\n  sandbox.ts             # Snapshot-aware wrapper around @vercel/sandbox\nscripts/\n  create-snapshot.ts     # Build-time: pre-bake the sandbox snapshot\npublic/\n  compositions/\n    vercel-intro/        # The bundled example composition\n      index.html\n      assets/\n```\n\n## Swapping the composition\n\n1. Drop your composition bundle into `public/compositions/\u003cyour-name\u003e/`.\n2. Update `PREVIEW_COMPOSITION_DIR` at the top of `lib/preview.ts` (used by both preview and render).\n3. Optionally update `COMPOSITION_WIDTH` / `COMPOSITION_HEIGHT` at the top of `app/page.tsx` to match your composition's dimensions.\n\n## Pricing\n\n[Vercel Sandbox pricing](https://vercel.com/docs/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.\n\n## License\n\n[Apache-2.0](./LICENSE) — same license as HyperFrames itself.\n\n## Links\n\n- [HyperFrames repo](https://github.com/heygen-com/hyperframes)\n- [HyperFrames docs](https://hyperframes.heygen.com)\n- [Vercel Sandbox docs](https://vercel.com/docs/vercel-sandbox)\n- [Vercel Blob docs](https://vercel.com/docs/vercel-blob)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheygen-com%2Fhyperframes-vercel-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheygen-com%2Fhyperframes-vercel-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheygen-com%2Fhyperframes-vercel-template/lists"}