Server rendering architecture#

Status: accepted, 2026-08-07

Decision#

SmolForge uses React 19 and React Router 8 Framework Mode for server rendering. The existing cloudforge-edge Worker remains the single public HTTP owner: it classifies API and protocol traffic, delegates those requests to the existing Identity, Repository, and Deploy Control services, and renders page requests. No product authority moves into the renderer.

The framework build produces two compatible artifacts:

• packages/edge/build/server contains the React Router server build and the generated Wrangler configuration.
• packages/edge/build/client contains the framework client assets plus the existing Vite SPA shell. The shell is the render-failure and rollout fallback.

The root toolchain pins Vite, esbuild, and the Cloudflare workerd version used by the Vite plugin. The Vite pin gives root-hoisted Vitest helpers a stable peer across workspaces; the esbuild and workerd pins keep npm clean installs from pruning their platform-specific optional binaries when the repository also contains older nested build tools.

Anonymous loaders receive typed service-binding adapters through React Router's request context. They never receive browser tokens, cookies, or local-storage state. Private and authenticated routes remain client-owned. Public and unlisted records are loaded without credentials, so the existing service owner continues to enforce visibility.

Public data policy#

• Public routes return semantic HTML and hydrate into the existing app.
• Unlisted Gists render for anyone holding the URL and emit noindex, nofollow.
• Private or unauthorized resources render only the client shell; their titles, filenames, and content are never serialized into HTML or loader data.
• Gist file excerpts share a 32 KiB UTF-8 byte budget per response.
• Repository and profile snapshots use an explicit presentation allowlist; no email or opaque authorization fields are serialized.

Static content routes (landing, docs, blog, changelog, and authentication form shells) render their existing React components directly. Stateful public route groups render typed server snapshots for the initial response, then hand over to the existing client experience after hydration.

Rollout and failure behavior#

SSR_ROLLOUT has three states:

• off: serve the existing SPA shell.
• canary: render only recognized bots or requests with X-Forge-SSR-Canary: 1.
• all: render every document request.

The first production version used canary, which made Slack unfurls readable without changing normal browser traffic. After the production canary passed, the rollout advanced to all. A render exception or server 5xx is served from the existing shell with X-Forge-Render: static-fallback. Rollback is the previous immutable Cloudflare Worker version; changing traffic does not require a data migration.

Rejected alternatives#

• A separate renderer Worker would duplicate hostname, asset, binding, and release ownership.
• TanStack Start would require a second routing contract while the product already depends on React Router throughout.
• Moving public reads to direct D1 access would bypass the established service owners and visibility policy.
• Raising long-running dispatch leases would hide ownership bugs. The build outbox event is delivered after workflow dispatch; release and workflow-run ledgers own the remaining build duration.