Deploying Next.js to Cloudflare Pages: The Complete 2025 Guide

When we rebuilt exagrowth.com on Next.js and Cloudflare Pages, the motivations were clear: faster global delivery, zero cold starts, zero infrastructure management, and a single git push to deploy. The reality was mostly that — with a few wrinkles worth documenting.

The first gotcha is Cloudflare Pages' Node.js compatibility. The edge runtime does not have the same APIs as Node.js, so anything that reaches for `fs`, `path`, or Node built-ins will break. We hit this with our Sanity client, which uses a Node-specific fetch configuration. The fix was to ensure all server-side Sanity calls used the standard `fetch` API and passed `cache: 'no-store'` where freshness was required.

The second issue was image optimisation. Cloudflare Pages does not run the Next.js Image Optimisation API — you need either a Cloudflare Image Resizing subscription or an external service. We used Cloudflare Images with a custom loader, which worked well but added a few hours of configuration work. If you are just getting started, `unoptimized: true` in your Next config is a reasonable temporary compromise.

Finally: `wrangler.toml`. Get comfortable with it early. Binding KV stores, R2 buckets, and environment variables all flow through wrangler config. Keeping a `wrangler.toml` committed (without secrets) and a `.dev.vars` locally is the right pattern. The Cloudflare dashboard is convenient but not a substitute for config-as-code.