Astro 5 SSR on Cloudflare Pages: Lessons Learned

Running Astro 5 in SSR mode on Cloudflare Pages has been a core part of the Flare CMS frontend from day one. Here are the lessons learned during development.

The PUBLIC_ Prefix Gotcha

This one cost us a production outage. In Cloudflare Pages, Astro's import.meta.env only works for variables prefixed with PUBLIC_. Without the prefix, your environment variable is silently undefined at runtime — even if it's set in wrangler.jsonc.

Our API URL was set as FLARE_API_URL instead of PUBLIC_FLARE_API_URL. The site deployed, the Worker was healthy, but every API call failed with "fetch failed" because the URL was empty.

No Sharp at Runtime

Cloudflare Workers don't support the Sharp image processing library at runtime. If you need image optimization, either handle it at build time (with imageService: "compile") or use Cloudflare Images.

SSR Means No getStaticPaths()

With output: 'server', every page is rendered on request. Dynamic routes like [slug].astro don't need getStaticPaths() — they just read the slug from Astro.params and fetch the content.

This simplifies the codebase significantly. No build-time data fetching, no incremental regeneration. Just fetch and render.

Wrangler JSON Config

Cloudflare Pages supports wrangler.jsonc for configuration. This is where you define your environment variables and bindings. The JSONC format allows comments, which is helpful for documenting what each binding does.