system
400.wtf

400.wtf / system / docs · docs/ADR/0007-cloudflare-workers-deployment.md

ADR-0007 — Cloudflare Workers deployment with full static prerender

Status: Accepted (documents the existing decision; keep-the-worker clause added 2026-07)

Context

All routes are statically prerendered (getStaticPaths, no server endpoints). The project deploys via @astrojs/cloudflare + wrangler, emitting a Worker that serves dist/ through an assets binding. nodejs_compat and observability are enabled.

Problem

The site is static; the adapter adds a server runtime it doesn’t strictly need. Is the Worker justified, or should deployment simplify to pure static hosting (CF Pages, Netlify, GitHub Pages)?

Decision

Keep the Workers adapter. The Worker is currently pass-through overhead, but it is the delivery mechanism for planned, cheap, on-brand features: custom response headers (branding R8 easter eggs), correct 404 semantics, future dynamic OG unfurls for config permalinks, and the (parked) KV-backed “the hole remembers” experiment. Cloudflare’s free tier absorbs the cost; wrangler.jsonc keeps config in-repo.

Alternatives considered

  • Cloudflare Pages (static): simpler mental model; headers possible via _headers file; but Pages is in maintenance-mode convergence with Workers, and dynamic futures would force a migration back.
  • GitHub Pages / Netlify static: fine hosts, but no edge-code path at all (GH) or a different vendor’s function model (Netlify); no benefit over the current setup.
  • Full SSR: nothing on the site is request-dependent; prerendering is strictly better for cold-load speed (the share-link case).

Tradeoffs

  • (+) One platform from static to dynamic; no future migration cliff.
  • (+) In-repo config, observability included, effectively free.
  • (−) A worker runtime in the serving path that mostly does nothing today.
  • (−) Vendor coupling (mild: the build output is standard static files + one adapter swap away from anywhere else).
  • (−) Wrangler/adapter version churn is a real (small) maintenance line item — covered by Renovate policy (deployment R5).

Consequences

  • Deploys must move from laptop to CI (deployment R1) — the Worker makes deploys a credentialed operation, which is exactly what shouldn’t depend on one machine.
  • Header/redirect behavior should be exercised by the CI smoke test once it exists.

Future evolution

  • If after Phase 3 no Worker-shaped feature has shipped, downgrade honestly to static hosting and supersede this ADR — carrying unused capability indefinitely is how projects rot.
  • If server state ever lands (KV counter), amend this ADR with data-handling notes (retention, anonymity) before shipping.