Shipping a React app to the edge without regrets

Deploying your React applications to edge runtimes (like Cloudflare Workers, Vercel Edge Functions, or AWS CloudFront Functions) gives you a mind-blowing 30ms Time-to-First-Byte (TTFB) in Sydney, Tokyo, and London. However, it also introduces a completely new category of production runtime errors.

Most edge deploy failures don't come from your React code itself. They happen because developers assume edge workers run on a full-blown Node.js virtual machine. They don't — they run on lightweight V8 isolates.

Things that are not there

Unlike standard server environments, edge runtimes stripped away many legacy Node.js C++ bindings to optimize for instantaneous cold-start times and minimal memory footprint.

When migrating an existing app or adding third-party packages, watch out for missing core APIs:

• child_process & process signals — Spawning subprocesses or relying on native OS signals is strictly impossible.
• Native C++ modules (sharp, canvas, sqlite3) — Heavy image manipulation or native database drivers won't compile unless ported to WebAssembly (WASM).
• Arbitrary filesystem access (fs.readFile) — There is no persistent local disk. Any dynamic runtime file path resolution will fail silently or throw runtime reference errors.

Bundle everything at build time

There is no dynamic runtime module resolution on V8 isolates. If a npm dependency attempts to lazily import an asset or resolve a path relative to __dirname at execution time, it will run fine in local development and explode instantly in production.

Always handle asset imports statically so your bundler (Vite, esbuild, or Turbopack) can inline or asset-tag them during the build step:

// safe: resolved at build time by your bundler
import wasm from "./resize.wasm?url";

// unsafe on the edge: resolved at runtime, causing dynamic file path failure
const wasmPath = require.resolve("./resize.wasm");

If it only breaks in production, you tested against the wrong runtime.

Local dev servers usually execute on top of standard Node.js environments and will happily mock or allow missing APIs that the actual edge worker will reject. To avoid deployment surprises, always run an edge-emulated production build locally (using tools like Wrangler or @vercel/nitro) before pushing code to your main branch.