Cloudflare Pages
Cloudflare’s static-site hosting service. The page you’re reading right now is served by Cloudflare Pages.
What we use it for
Section titled “What we use it for”One Pages project: agent-platform-docs. Hosts the apps/docs/
directory’s build output (Astro + Starlight static site). Served
from Cloudflare’s edge worldwide.
Two deploy modes are available:
- Manual —
wrangler pages deploy ./distfrom a local build - Git-driven (recommended) — point Pages at the
agent-platformrepo, set the build command topnpm --filter @agent-platform/docs build, and every push tomaintriggers a deploy with a unique URL. PRs get preview URLs automatically.
No Worker, no D1, no functions. Pure static HTML/CSS/JS.
Why we picked it
Section titled “Why we picked it”The choice was: where do we host the docs site?
| Option | Verdict |
|---|---|
| Cloudflare Pages | Chosen. Pages is purpose-built for static sites; git-driven deploys + preview URLs out of the box; same account as the rest of the stack. |
| GitHub Pages | Free, but gives up the unified Cloudflare-account story we tell investors. |
| Vercel / Netlify | Strong alternatives but introduce a third vendor for documentation alone. |
| A second Cloudflare Worker | Possible — Workers can serve static assets — but Pages is the right tool for the job. Reaching for a Worker would be reinventing what Pages already does. |
| Self-hosted (S3 + CloudFront, etc.) | Significant setup for no benefit. |
Pages won as the obvious fit. We considered serving the docs from a Worker briefly (the platform Worker isn’t a docs server, but a dedicated docs Worker would be); decided against it because docs are pure static content and Pages is the purpose-built service.
What it costs
Section titled “What it costs”Cloudflare Pages free tier:
- Unlimited sites
- Unlimited requests
- 500 builds per month
- 100 custom domains per project
Phase 1’s docs site uses ~5 builds per week. Free tier covers us indefinitely at this rate.
What it replaces
Section titled “What it replaces”A documentation host like Read the Docs, GitBook, Confluence, or a self-hosted Hugo deploy. Pages reduces this to a wrangler.jsonc file + the build output directory.
Where to look
Section titled “Where to look”apps/docs/wrangler.jsonc— Pages deploy config (very small)apps/docs/astro.config.mjs— Astro + Starlight site configapps/docs/src/content/docs/— the markdown content treeapps/docs/README.md— local-dev + deploy runbook
Trade-offs we accepted
Section titled “Trade-offs we accepted”- Pure static. No server-side rendering, no API routes, no per-visitor personalization. This is fine; docs don’t need any of those. If we ever need a “try it” widget that talks to the platform Worker, the widget runs client-side and hits the platform Worker’s public URL.
- Build-time only. Content updates require a rebuild (~22 seconds). For a docs site this is fine. For a high-frequency- update scenario (a status page, a live dashboard) this would be wrong.
- No git LFS for large media. Pages builds from the git repo’s contents; very large binaries (videos, big PNGs) would inflate clone times. We keep media small or move it to R2 if needed.