From 3978393932591839eaa54ecb29e1a49cc7facff8 Mon Sep 17 00:00:00 2001 From: James Date: Wed, 6 May 2026 23:00:14 +0000 Subject: [PATCH 1/3] docs(guides): add deployment guide for Vercel and Cloudflare templates Surfaces the two official one-click deployment templates (heygen-com/hyperframes-vercel-template, heygen-com/hyperframes-cloudflare-template) in the docs site. Previously they only existed as GitHub READMEs. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/docs.json | 1 + docs/guides/deploy.mdx | 146 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 docs/guides/deploy.mdx diff --git a/docs/docs.json b/docs/docs.json index 29072f1df..1476228cf 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -77,6 +77,7 @@ "guides/hyperframes-vs-remotion", "guides/gsap-animation", "guides/rendering", + "guides/deploy", "guides/remove-background", "guides/hdr", "guides/performance", diff --git a/docs/guides/deploy.mdx b/docs/guides/deploy.mdx new file mode 100644 index 000000000..1bec166bc --- /dev/null +++ b/docs/guides/deploy.mdx @@ -0,0 +1,146 @@ +--- +title: Deploy +description: "Run a Hyperframes preview + render API on Vercel or Cloudflare with one click." +--- + +Hyperframes ships two official deployment templates that wrap a composition in a small web app: an in-browser preview and a `/api/render` endpoint that produces an MP4 server-side. Both are open source, Apache-2.0, and deploy in one click. + +| Template | Compute | Storage | Deploy | +|----------|---------|---------|--------| +| [Vercel](https://github.com/heygen-com/hyperframes-vercel-template) | [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) (Firecracker microVM) | [Vercel Blob](https://vercel.com/docs/vercel-blob) | [vercel.com/templates/ai/hyperframes-on-vercel](https://vercel.com/templates/ai/hyperframes-on-vercel) | +| [Cloudflare](https://github.com/heygen-com/hyperframes-cloudflare-template) | [Cloudflare Containers](https://developers.cloudflare.com/containers/) (Workers + Durable Object) | [R2](https://developers.cloudflare.com/r2/) | One-click button in the repo README | + +Both templates use the same shape: + +- **Preview** the bundled `ui-3d-reveal` composition in the browser via the [``](/packages/player) web component. +- **Render** to MP4 by POSTing to `/api/render`. The handler ships the composition to a sandboxed runtime that has Chromium, FFmpeg, and `hyperframes` pre-installed, then streams the MP4 back to object storage and returns a public URL. +- **Author locally**, deploy the preview + render API. Compositions are still built on your machine with `npx hyperframes init`, then dropped into the template's `public/compositions/` directory. + +## Choosing a template + + + + Pick this if you already deploy on Vercel, want zero-config Blob storage, or want to reuse Vercel's CI/preview environments. + + [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fheygen-com%2Fhyperframes-vercel-template&stores=%5B%7B%22type%22%3A%22blob%22%2C%22access%22%3A%22public%22%7D%5D) + + **What you get** + + - A Next.js app with `` preview and a `POST /api/render` route. + - A pre-baked Vercel Sandbox snapshot built during `next build` — cold renders skip the Chromium/FFmpeg install and restore from snapshot in ~100 ms. + - A Vercel Blob store provisioned automatically on deploy. `BLOB_READ_WRITE_TOKEN` is injected for you. + + **Performance** + + Cold render of a 20-second composition is ~70 seconds on `standard-4` (4 vCPU). With `--workers auto`, three parallel Chrome workers cut render time roughly 2× vs. single-worker. + + **Pricing** + + Vercel Pro plans include $20/mo of Sandbox credit, which covers ~100 renders/month of the bundled 20-second example. See [Vercel Sandbox pricing](https://vercel.com/docs/vercel-sandbox/pricing). + + + Vercel Functions cap at 300s and a 50 MB compressed bundle, which can't fit Chromium + FFmpeg. The template uses Vercel Sandbox specifically because it's the purpose-built primitive for this workload — up to 5 hours of runtime and up to 8 vCPUs per render. + + + + Pick this if you're already on Cloudflare Workers, want R2's free egress, or want full control over the renderer image. + + [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/heygen-com/hyperframes-cloudflare-template) + + **What you get** + + - A Worker that serves preview HTML and forwards `/api/render` requests to a `RenderContainer` Durable Object. + - A pre-built OCI container image with Chromium + FFmpeg + `hyperframes` baked in — no install at request time. + - An R2 bucket (`hyperframes-renders`) provisioned automatically on deploy. + + **Performance** + + Cold render of a 13-second composition is ~25 seconds on `standard-4` (4 vCPU, 12 GiB). With `--workers auto`, three parallel Chrome workers cut render time roughly 2× vs. single-worker. Container instances sleep after 10 minutes of inactivity. + + **Pricing** + + Cloudflare Containers bills per-10ms for memory, CPU, and disk. A 70-second render on `standard-4` costs ~$0.008. R2 storage is $0.015/GB-month with no egress within Cloudflare's network. Requires a [Workers Paid](https://developers.cloudflare.com/workers/platform/pricing/) plan. See [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/). + + + Cloudflare's hosted [Browser Rendering](https://developers.cloudflare.com/browser-rendering/) API can't install FFmpeg — that's why the template uses Cloudflare Containers, which gives you a real OCI container in a Worker-bound Durable Object with up to 4 vCPUs and 12 GiB RAM. + + + + +## Architecture + +Both templates follow the same flow: the browser plays a preview locally, then POSTs to a render endpoint that delegates to a sandboxed runtime with Chromium + FFmpeg. + +``` + Browser Edge / Function Sandboxed renderer +┌──────────────────┐ ┌────────────────────┐ ┌──────────────────────────┐ +│ │ │ ship composition │ │ (Chromium + FFmpeg, │ +│ preview iframe │ │ → renderer │ │ pre-installed) │ +│ │ ◀──── │ ← stream MP4 │ ◀──── │ │ +│ │ url │ → upload to blob │ mp4 │ │ +└──────────────────┘ └────────────────────┘ └──────────────────────────┘ + │ + └─▶ Vercel Blob / Cloudflare R2 +``` + +The key cost-saver in both templates is **pre-baking the renderer**. Installing Chromium system libraries plus `chrome-headless-shell` takes 30–60s, which would dominate every cold render. Vercel's template snapshots the sandbox at build time; Cloudflare's template bakes everything into the container image. Both restore in milliseconds and let you spend the entire request budget on actual rendering. + +## Swapping the composition + +Both templates ship with one bundled composition (`ui-3d-reveal`). To use your own: + + + + Compositions are HTML — author them on your machine with the [CLI](/packages/cli): + + ```bash Terminal + npx hyperframes init my-video + cd my-video + npx hyperframes preview + ``` + + + Copy your composition into `public/compositions//`. + + + - **Vercel**: edit `PREVIEW_COMPOSITION_DIR` at the top of `lib/preview.ts` and the dimensions in `app/page.tsx` if it isn't 1920×1080. + - **Cloudflare**: set `PREVIEW_COMPOSITION_DIR=compositions/` when running `npm run deploy`, or edit the default in `scripts/build.mjs`. Update player dimensions in `public/index.html` if needed. + + + ```bash Terminal + # Vercel + vercel deploy + + # Cloudflare + npm run deploy + ``` + + + +## When to use a template vs. roll your own + +Templates are optimized for **a single render endpoint behind a preview UI**. They're the fastest way to get a hosted Hyperframes render API running. If you need: + +- A **render queue** with retries, deduplication, or priorities — start from a template, then add your own queue (e.g. Vercel Queues, Cloudflare Queues, SQS). +- **Multi-tenant rendering** with per-user composition uploads — start from a template, replace the bundled composition with a runtime-fetched one. +- **Self-hosted** rendering — see the [Rendering guide](/guides/rendering) and run `hyperframes render --docker` on your own infrastructure. + +For everything else, the templates are the recommended starting point. + +## Next Steps + + + + Render compositions locally or in Docker + + + Embed `` in any HTML page + + + Source on GitHub + + + Source on GitHub + + From 34c01b22aa0178e15e1cebdcab6a92a1eab0f2b5 Mon Sep 17 00:00:00 2001 From: James Date: Wed, 6 May 2026 23:05:58 +0000 Subject: [PATCH 2/3] docs(guides): address PR review on deploy guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Reword frontmatter description to describe capability, not providers - Soften "deploy in one click" — Cloudflare requires Workers Paid plan - Qualify Cloudflare ~25s perf number as a local-Docker measurement on a 6-vCPU host, not a standard-4 production figure Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/deploy.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/deploy.mdx b/docs/guides/deploy.mdx index 1bec166bc..80a3a9999 100644 --- a/docs/guides/deploy.mdx +++ b/docs/guides/deploy.mdx @@ -1,9 +1,9 @@ --- title: Deploy -description: "Run a Hyperframes preview + render API on Vercel or Cloudflare with one click." +description: "Run a Hyperframes preview + render API in the cloud from a one-click template." --- -Hyperframes ships two official deployment templates that wrap a composition in a small web app: an in-browser preview and a `/api/render` endpoint that produces an MP4 server-side. Both are open source, Apache-2.0, and deploy in one click. +Hyperframes ships two official deployment templates that wrap a composition in a small web app: an in-browser preview and a `/api/render` endpoint that produces an MP4 server-side. Both are open source, Apache-2.0, and deploy from a single button. | Template | Compute | Storage | Deploy | |----------|---------|---------|--------| @@ -55,7 +55,7 @@ Both templates use the same shape: **Performance** - Cold render of a 13-second composition is ~25 seconds on `standard-4` (4 vCPU, 12 GiB). With `--workers auto`, three parallel Chrome workers cut render time roughly 2× vs. single-worker. Container instances sleep after 10 minutes of inactivity. + With `--workers auto` on `standard-4` (4 vCPU, 12 GiB), three parallel Chrome workers cut render time roughly 2× vs. single-worker. The bundled 13-second composition renders in ~25 seconds when tested locally against the container image on a 6-vCPU host (`scripts/test-render.mjs`); production timings on `standard-4` will vary with composition length and complexity. Container instances sleep after 10 minutes of inactivity. **Pricing** From ea1637cdeca2958afc0dec095b6a99e524189e20 Mon Sep 17 00:00:00 2001 From: James Date: Wed, 6 May 2026 23:07:08 +0000 Subject: [PATCH 3/3] docs(guides): drop specific perf/pricing numbers from deploy guide Remove dollar amounts, render-time figures, and credit allowances from the Vercel/Cloudflare tabs. These were sourced from the template READMEs but go stale fast (pricing changes) and are load-bearing on a single composition's quirks (perf isn't proportional to duration). Keep qualitative framing and link out to the canonical pricing pages instead. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/deploy.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/deploy.mdx b/docs/guides/deploy.mdx index 80a3a9999..cf09ac17b 100644 --- a/docs/guides/deploy.mdx +++ b/docs/guides/deploy.mdx @@ -32,11 +32,11 @@ Both templates use the same shape: **Performance** - Cold render of a 20-second composition is ~70 seconds on `standard-4` (4 vCPU). With `--workers auto`, three parallel Chrome workers cut render time roughly 2× vs. single-worker. + Renders run on `standard-4` (4 vCPU). With `--workers auto`, three parallel Chrome workers cut render time meaningfully vs. single-worker. Concrete render time depends on composition length, complexity, and asset size. **Pricing** - Vercel Pro plans include $20/mo of Sandbox credit, which covers ~100 renders/month of the bundled 20-second example. See [Vercel Sandbox pricing](https://vercel.com/docs/vercel-sandbox/pricing). + Vercel Pro plans include Sandbox credit each month. See [Vercel Sandbox pricing](https://vercel.com/docs/vercel-sandbox/pricing) for current per-vCPU and per-GB rates and the up-to-date credit allowance. Vercel Functions cap at 300s and a 50 MB compressed bundle, which can't fit Chromium + FFmpeg. The template uses Vercel Sandbox specifically because it's the purpose-built primitive for this workload — up to 5 hours of runtime and up to 8 vCPUs per render. @@ -55,11 +55,11 @@ Both templates use the same shape: **Performance** - With `--workers auto` on `standard-4` (4 vCPU, 12 GiB), three parallel Chrome workers cut render time roughly 2× vs. single-worker. The bundled 13-second composition renders in ~25 seconds when tested locally against the container image on a 6-vCPU host (`scripts/test-render.mjs`); production timings on `standard-4` will vary with composition length and complexity. Container instances sleep after 10 minutes of inactivity. + Renders run on `standard-4` (4 vCPU, 12 GiB). With `--workers auto`, three parallel Chrome workers cut render time meaningfully vs. single-worker. Container instances sleep after 10 minutes of inactivity, so the next request after a quiet period pays a cold-start penalty. **Pricing** - Cloudflare Containers bills per-10ms for memory, CPU, and disk. A 70-second render on `standard-4` costs ~$0.008. R2 storage is $0.015/GB-month with no egress within Cloudflare's network. Requires a [Workers Paid](https://developers.cloudflare.com/workers/platform/pricing/) plan. See [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/). + Cloudflare Containers bills per-10ms for memory, CPU, and disk; R2 storage has no egress within Cloudflare's network. Requires a [Workers Paid](https://developers.cloudflare.com/workers/platform/pricing/) plan. See [Cloudflare Containers pricing](https://developers.cloudflare.com/containers/pricing/) and [R2 pricing](https://developers.cloudflare.com/r2/pricing/) for current rates. Cloudflare's hosted [Browser Rendering](https://developers.cloudflare.com/browser-rendering/) API can't install FFmpeg — that's why the template uses Cloudflare Containers, which gives you a real OCI container in a Worker-bound Durable Object with up to 4 vCPUs and 12 GiB RAM.