Deploying Astro to Cloudflare Workers: Architecture Plan

Overview

Cloudflare Workers runs JavaScript at the edge, globally distributed, with zero cold starts. Combined with Astro’s hybrid output mode, we get static pages for content and server-rendered pages for dynamic functionality.

Architecture Decision

output: 'hybrid'
  ├── Static pages (prerendered at build time)
  │   ├── /ideas/[slug]    → prerendered MDX
  │   └── /               → static homepage
  └── Server pages (rendered on each request)
      ├── /lab/*           → dynamic tools
      └── /api/*           → API routes

Configuration Checklist

• @astrojs/cloudflare adapter installed
• output: 'hybrid' set in astro.config
• platformProxy.enabled: true for local dev
• wrangler.jsonc configured
• KV namespace bound for caching (optional)
• D1 database bound if needed

Build & Deploy Commands

npm run build       # builds to dist/
wrangler deploy     # deploys to Cloudflare

Performance Notes

• Workers have a 128MB memory limit — avoid large imports
• Use export const prerender = true on static pages
• Images should be served from Cloudflare Images or R2
• Environment variables set via wrangler secret put VAR_NAME

Known Limitations

• sharp image processing is incompatible with Workers — use squoosh or disable image processing
• Node.js APIs unavailable unless using nodejs_compat compatibility flag