Cloudflare Static Deploy

Cloudflare Static Deploy

How wcygan.net ships: prerender every route to flat HTML/JS/CSS, upload via Workers Assets, no server at runtime. No @cloudflare/vite-plugin, no wrangler runtime coupling in app code.

Why static, not SSR

The blog has zero per-request logic. Homepage, /posts, /{slug}, /about, /resume, /feed, /mermaid-examples are all content-static. Mermaid diagrams are rendered to static SVG at build time, so they ship as plain images with no client-side JavaScript. RSS is a committed public/rss.xml. Prerendering beats SSR on cost, latency, portability, and operational surface.

If we ever add auth, per-user data, or build-time bindings (KV/D1), revisit — see "When to switch to the Workers runtime" below.

Required pieces

1. vite.config.ts — prerender + keep Nitro deno-server preset

tanstackStart({
  srcDirectory: 'src',
  prerender: {
    enabled: true,
    crawlLinks: true,
    autoSubfolderIndex: true,
    failOnError: true,
  },
}),
react(),
nitro({ preset: 'deno-server' }),

• Do NOT use preset: 'static'. Nitro's own prerenderer with that preset does not know about TanStack Start's route handlers and 404s on every path. TanStack Start runs its own prerender against the Nitro-built server via a preview server. Keeping preset: 'deno-server' gives it a Deno-compatible server to probe, and the prerendered HTML lands in .output/public/ alongside a server bundle in .output/server/ that we simply don't ship.
• crawlLinks discovers posts via links from / and /posts. Every post must be reachable from a crawled page, otherwise add it to prerender.pages: ['/slug-a', ...].
• autoSubfolderIndex emits /posts/foo/index.html (correct for Workers Assets routing) rather than /posts/foo.html.

Mermaid is build-time only now (the render script serves it to a headless Chrome; it never enters the client or server bundle), but the alias and ssr.external entry still guard any stray import. Keep the Mermaid alias as a regex — a string alias gets re-applied by Nitro's SSR bundler and produces mermaid/dist/.../dist/... paths that fail to resolve:

resolve: {
  alias: [
    { find: '~', replacement: new URL('./src', import.meta.url).pathname },
    { find: /^mermaid$/, replacement: 'mermaid/dist/mermaid.esm.min.mjs' },
  ],
},
ssr: { external: ['mermaid'] },

2. wrangler.jsonc — assets-only Worker

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "wcygan-net",
  "compatibility_date": "2026-04-13",
  "assets": {
    "directory": ".output/public",
    "not_found_handling": "404-page",
  },
}

No main. No nodejs_compat. Wrangler is a deploy CLI only — not a runtime dependency. Keep the file minimal; every added field is a coupling point.

3. deno.json tasks

"build": "vite build",
"deploy": "deno task build && wrangler deploy",
"preview-static": "deno run --allow-net --allow-read --allow-sys jsr:@std/http@1/file-server .output/public"

Delete any start script pointing at .output/server/index.mjs — that file no longer exists under the static preset.

4. Cloudflare Workers Builds dashboard

The Workers Builds image as of 2026-05 ships Bun and Node, but not Deno, so we install Deno inline. CF auto-runs bun install first (because package.json exists); that's fine — the build command then layers Deno on top for the actual build.

Three non-obvious requirements baked into those commands:

1. Pin the Deno version (v2.6.10 as the sh -s positional arg — see install script source). The unpinned curl | sh form grabs the latest release, and newer Deno tightens node:_http_server.writeHead argument validation, which breaks srvx@0.11.15 during TanStack Start's prerender step. Bump the pin only after locally rebuilding on a newer Deno and confirming .output/public/*.html still emits.
2. Each command exports $HOME/.deno/bin to PATH independently. The build command's export doesn't persist — deploy commands run in a fresh shell. Without the re-export you get /bin/sh: 1: deno: not found.
3. deno x wrangler ... replaces bunx and deno task --eval. deno x is the npx/bunx equivalent (since Deno 2). It resolves wrangler from node_modules populated by deno install --frozen. No Bun on the deploy path.

Enable Build cache to reuse node_modules across builds.

Commit only deno.lock — never bun.lock, pnpm-lock.yaml, or package-lock.json alongside it.

Verification checklist after deno task build

• .output/public/index.html exists and is non-empty (silent prerender failure can leave the dir asset-only)
• .output/public/posts/index.html exists
• .output/public/<slug>/index.html exists for every MDX post
• .output/public/rss.xml present (copied from public/)
• .output/server/ exists (Nitro Deno bundle — we just don't deploy it; wrangler.jsonc has no main, only assets.directory)
• Total .output/public/ size sane (posts + mermaid client chunk)
• Build log contains [prerender] Prerendered N pages: with the expected route list, not Prerendered 0 pages:

scripts/build.mjs must fail loudly

TanStack Start's prerender step rejects with an unhandledRejection rather than throwing, so a naïve try/catch + process.exit(0) builder script reports success even when zero HTML emitted. Guard against this at the top of scripts/build.mjs:

process.on("unhandledRejection", (err) => {
  console.error("Unhandled rejection during build:", err);
  process.exit(1);
});

Without this, a broken prerender produces a deploy that uploads only /assets/*.js and yields a 404 on every route — the failure mode behind the May 2026 outage.

Catch-all route gotcha

src/routes/$slug.tsx rejects slugs containing dots in beforeLoad. Keep this. Static files (rss.xml, favicon.ico) live in public/ and Workers Assets serves them before the catch-all is ever consulted. If you rename the guard logic, prerender will try to render /rss.xml as a post — don't.

Common failure modes

When to switch to the Workers runtime

Only if ALL of these become true:

• Need to read request context (cookies, auth) server-side
• Need Cloudflare bindings (KV, D1, R2, Queues, DO)
• Need ISR / on-demand revalidation

Then: install @cloudflare/vite-plugin + wrangler, replace Nitro with the Cloudflare plugin, add main: "@tanstack/react-start/server-entry" and compatibility_flags: ["nodejs_compat"] to wrangler.jsonc. See the Cloudflare TanStack Start framework guide (link below).

Reference docs

Primary:

• TanStack Start — Static Prerendering — prerender config shape; crawler behavior
• Nitro — Deployment presets — static preset and output layout
• Cloudflare Workers — Static Assets — assets binding in wrangler.jsonc, not_found_handling modes
• Cloudflare Workers Builds — Build configuration — dashboard build and deploy fields

Secondary / "if we migrate to Workers runtime":

• Cloudflare — TanStack Start framework guide — the SSR-on-Workers path
• Cloudflare — Wrangler vs Vite plugin — when each is appropriate
• Cloudflare Changelog (Dec 19, 2025) — TanStack Start prerendering — prerender combined with bindings
• TanStack Start — Incremental Static Regeneration — if we outgrow pure static

Adjacent project skills:

• wcygan-net-stack — stack fundamentals (Deno, TanStack Start, MDX, Mermaid)
• github-actions-troubleshooter — CI failures that aren't Cloudflare-specific