docs: add deployment guide for Vercel and Cloudflare templates

[jrusso1020]

What

Adds a new guide at docs/guides/deploy.mdx covering the two official one-click deployment templates:

• heygen-com/hyperframes-vercel-template (Vercel Sandbox + Vercel Blob)
• heygen-com/hyperframes-cloudflare-template (Cloudflare Containers + R2)

Wires the new page into docs.json under Guides, slotted right after guides/rendering (logical follow-on: render locally → deploy to the cloud).

Why

The two templates currently only exist as GitHub READMEs, so they're invisible to anyone reading the docs site. New users who want a hosted preview + render endpoint have no entry point in the docs to discover them.

How

Single guide with:

• A comparison table (compute / storage / deploy button) so readers can pick at a glance.
• <Tabs> for per-platform details (deploy button, what you get, performance, pricing, "why this primitive").
• Shared architecture diagram and the common "pre-baked renderer" cost pattern.
• "Swapping the composition" steps that work for both templates.
• "When to use a template vs. roll your own" framing for queues, multi-tenant, self-hosted.

Single-page approach (vs. one page per template) chosen because content overlaps heavily — easier to discover and lower maintenance until more templates land.

Test plan

• No code changes — docs only
• bunx oxfmt --check and bunx oxlint pass on changed files (no rules apply to .mdx / .json here)
• Render the docs site locally to verify nav placement and Mintlify components (<Tabs>, <Steps>, <CardGroup>, <Note>) render correctly
• Verify the Vercel and Cloudflare deploy buttons in the page open the correct template URLs

[jrusso1020]

do we want to name every provider here is this best practice?

[jrusso1020]

Reworded in 34c01b2 — frontmatter now reads "Run a Hyperframes preview + render API in the cloud from a one-click template." and the intro paragraph drops the "deploy in one click" phrasing. The provider names stay in the comparison table and tabs where they belong.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	May 6, 2026, 11:05 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[jrusso1020]

Verdict

Comment / would-approve — net-positive ship (GitHub blocks self-approval, otherwise this would be Approve+comments). The doc is internally consistent and matches the upstream READMEs. One factual misattribution worth fixing pre-merge; everything else is style/framing.

Key Concerns

• docs/guides/deploy.mdx:58 — Cloudflare perf number is misattributed. The ~25s figure in the Cloudflare README comes from node scripts/test-render.mjs against a local Docker container on a 6-vCPU host, not from a deployed Cloudflare standard-4 (4 vCPU) instance. As written, the doc implies the 25s is the production number on standard-4. Either (a) drop the perf number from the Cloudflare tab, (b) qualify it as "in local Docker on a 6-vCPU host", or (c) replace with an actual standard-4 measurement if you have one.
• docs/guides/deploy.mdx:3 — frontmatter description names two specific providers. Author already flagged this inline. Agree — "Run a Hyperframes preview + render API on Vercel or Cloudflare with one click." ties the description to the current two templates and reads vendor-y. Other guides describe the capability (e.g. rendering.mdx: "Render compositions to MP4, MOV, or WebM locally or in Docker"). Suggest something like "Run a Hyperframes preview + render API in the cloud with one click." and let the body name brands.

Test Coverage

Docs-only PR. Manual verification needed:

• Mintlify preview renders <Tabs>, <Steps>, <CardGroup>, <Note> correctly and the new entry shows up under Guides
• Both deploy buttons (Vercel and Cloudflare) actually clone/provision when clicked
• File paths cross-checked against template repos: lib/preview.ts ✓ (Vercel), scripts/test-render.mjs ✓ (Cloudflare), scripts/build.mjs, app/page.tsx, public/index.html all match the READMEs.

Nits / Future

• docs/guides/deploy.mdx:6 — "deploy in one click" is slightly aspirational for Cloudflare, which requires a Workers Paid plan first (the doc itself notes this in the Cloudflare tab). Could soften to "deploy with a single button."
• Architecture diagram (lines 74–85) — the dangling arrow to "Vercel Blob / Cloudflare R2" is hanging off the Function box without a return arrow back, which is fine, but the body text says the function returns a URL after upload. Could clarify: the URL returned to the browser points at the blob/R2 object. Minor.
• Vercel deploy button URL (line 25) — strips the demo-title / demo-description / demo-image query params that the upstream README's button uses. They're not required for the clone to work, but the marketplace listing context is lost. Either way is fine.
• Self-review on a docs PR — fine, just flagging that the only prior approval signal is from the author. A second pair of eyes (designer or DX) before merging would be worth it for the framing call (single-page vs split-per-template) since it sets the precedent for future templates.

[jrusso1020]

Addressed review feedback in 34c01b2:

1. Frontmatter description (your inline comment) — reworded to describe the capability, not specific providers.
2. Cloudflare perf misattribution — the ~25s number now explicitly notes it's a local-Docker measurement on a 6-vCPU host (scripts/test-render.mjs), not a standard-4 production figure.
3. "Deploy in one click" in the intro — softened to "deploy from a single button" since Cloudflare requires a Workers Paid plan.

Skipped the architecture diagram + Vercel button URL nits (purely cosmetic). Happy to revisit either if you want.

[jrusso1020]

Dropped specific numbers in ea1637c. Both Performance + Pricing sections now describe the shape ('renders run on standard-4', 'bills per-10ms') and link to the canonical pricing pages — no dollar amounts or render-time figures to maintain in our docs.

[miguel-heygen]

Docs-only PR, thorough verification below. Looks good to ship.

What I checked:

• Both template repos exist and are accessible (heygen-com/hyperframes-vercel-template, heygen-com/hyperframes-cloudflare-template).
• Internal doc links all resolve: /packages/player -> docs/packages/player.mdx, /packages/cli -> docs/packages/cli.mdx, /guides/rendering -> docs/guides/rendering.mdx, /concepts/determinism -> docs/concepts/determinism (in docs.json).
• Deploy button URLs decode correctly — Vercel button clones the right repo with blob store config, Cloudflare button points at the right repo.
• ui-3d-reveal composition exists in the registry (registry/blocks/ui-3d-reveal/).
• hyperframes render --docker flag exists in the CLI source and is documented in the rendering guide.
• Nav placement in docs.json is logical — right after guides/rendering (local render -> cloud deploy).
• Frontmatter description follows the pattern of other guides (capability-focused, not vendor-specific), consistent with the follow-up commit fix.
• All CI checks pass, including Validate docs and Mintlify Deployment.
• No secrets, env vars, or credentials exposed. BLOB_READ_WRITE_TOKEN is correctly described as auto-injected by Vercel, not hardcoded.
• Mintlify components (<Tabs>, <Steps>, <CardGroup>, <Note>) are used consistently with other guides in the repo.
• External links to Vercel/Cloudflare docs use canonical URLs.

The three follow-up commits cleanly address the earlier review concerns (vendor-neutral description, dropping unverified perf/pricing numbers). No issues found.

[vanceingalls]

Verdict: Approve. Scoped pure-docs PR. Cross-checked every load-bearing claim against both template repos and the existing docs nav — nothing is wrong. Ship it.

Praise

• Single-page approach is the right call. Vercel and Cloudflare templates share ~80% of the surface (preview UI, /api/render, pre-baked renderer, swap-the-composition flow). Splitting into two pages would have meant maintaining two copies of the same architecture diagram and the same "swap the composition" section. Easier to keep accurate as one page.
• Honest about platform choice. The two <Note> callouts ("Vercel Functions can't fit Chromium + FFmpeg → Sandbox", "Cloudflare Browser Rendering can't install FFmpeg → Containers") explain why each template uses the primitive it does, which is the question a thoughtful reader will ask. Saves a Slack thread later.
• Good response to prior review feedback in the commit history: dropped specific dollar amounts and render-time figures (those go stale fast and aren't proportional across compositions anyway), qualified the Cloudflare Workers Paid requirement, softened "deploy in one click."
• "When to use a template vs. roll your own" section sets expectations correctly — templates are for "single render endpoint behind a preview UI", and the queue / multi-tenant / self-hosted escape hatches are explicit.

Nits

• nit docs/guides/deploy.mdx:139 — ## Next Steps is title-case, every other H2 in this file is sentence-case ("Choosing a template", "Architecture", "Swapping the composition", "When to use a template..."). Trivial; just sentence-case it for consistency.
• nit docs/guides/deploy.mdx:5 — "deploy from a single button" in the lede is slightly at odds with the Cloudflare <Note> requiring a Workers Paid plan. You already softened the Cloudflare tab; the lede could match (e.g. "deploy from a one-click template" — which is what the title says anyway).
• nit docs/guides/deploy.mdx:71 — The pre-bake explanation says installing Chromium + chrome-headless-shell takes "30–60s". The Vercel template README's create-snapshot script does the same six steps (dnf install libs → npm install hyperframes ffmpeg-static → hyperframes browser ensure) and the Cloudflare Dockerfile does the equivalent at image build time. Number is plausible and sourced from the templates, but it's the kind of figure that drifts (Chromium versions, mirror speed). Optional to caveat as "tens of seconds" or drop the number — same shape as the perf/pricing trim you already did.
• nit docs/guides/deploy.mdx:92 — In the ASCII diagram, "Vercel Blob / Cloudflare R2" branches off the middle box, which is fine, but the Cloudflare reality is "Worker streams response body straight to R2 PutObject" while Vercel is "function buffers MP4 then put() to Blob". The simplification is acceptable for a one-pager — flagging only because if a reader copies this mental model and tries to add a long render to Vercel, they'll wonder why the function memory is the bottleneck. Optional; can stay as-is.

Verified

• Both template repos exist (heygen-com/hyperframes-vercel-template, heygen-com/hyperframes-cloudflare-template) and their descriptions match the doc.
• lib/preview.ts in the Vercel template exports PREVIEW_COMPOSITION_DIR at the top — Step 3 instruction is correct.
• app/page.tsx in the Vercel template has COMPOSITION_WIDTH = 1920; COMPOSITION_HEIGHT = 1080 — Step 3 1920×1080 reference is correct.
• scripts/build.mjs in the Cloudflare template reads process.env.PREVIEW_COMPOSITION_DIR ?? "compositions/ui-3d-reveal" — Step 3 env-var override instruction is correct.
• public/index.html in the Cloudflare template hardcodes width="1920" height="1080" — Step 3 "update player dimensions" is correct.
• docs.json nav slot is right after guides/rendering, exactly as the PR body claims.
• /packages/player and /packages/cli cross-links resolve (both pages exist in docs/packages/).
• Tooling style (npx hyperframes init, npm run deploy, vercel deploy) matches existing quickstart.mdx and rendering.mdx, which use npx not bunx. No inconsistency.
• Mintlify components (<Tabs>, <Tab>, <Steps>, <Step>, <Note>, <CardGroup>, <Card>) are all used elsewhere in this docs site (e.g. quickstart.mdx, rendering.mdx).
• Pure docs PR — no template code changes sneaking in.

— Vai

[jrusso1020]

Merge activity

• May 6, 11:18 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 6, 11:18 PM UTC: @jrusso1020 merged this pull request with Graphite.