This document covers React Router's integration with Cloudflare Workers and Cloudflare Pages, including the @react-router/cloudflare package, development workflows, and edge runtime considerations. For Node.js-based deployments, see Node.js and Express. For AWS Lambda deployments, see AWS Lambda and Other Platforms.
The @react-router/cloudflare package provides platform abstractions for deploying React Router applications to Cloudflare's edge runtime, including Cloudflare Workers and Cloudflare Pages.
Sources:
The package provides:
| Feature | Description |
|---|---|
| Platform Abstraction | Runtime-specific implementations for Cloudflare's edge environment |
| Session Storage | KV-based, Durable Objects-based, and cookie session storage implementations |
| Web Crypto API | Uses native crypto global for cookie and session APIs |
| TypeScript Types | Integration with @cloudflare/workers-types for type safety |
| Unified API | Consolidates previous @remix-run/cloudflare and @remix-run/cloudflare-pages packages |
The package requires Node.js 20+ and TypeScript 5.1+ when using TypeScript.
Sources:
For local development, React Router uses Miniflare to simulate the Cloudflare Workers runtime:
Sources:
The Vite plugin for Cloudflare integration is configured via the @cloudflare/vite-plugin package:
The @react-router/dev package exports a Vite plugin specifically for Cloudflare at @react-router/dev/vite/cloudflare.
Sources:
React Router provides session storage implementations that work with Cloudflare's platform primitives.
All session storage implementations use the Web Crypto API for signing and encrypting cookie data. The crypto global must be available in the runtime environment.
Sources:
Starting with React Router v7, cookie and session APIs are provided directly from the react-router package rather than platform-specific packages:
| API | Import From |
|---|---|
createCookie | react-router |
createCookieSessionStorage | react-router |
createMemorySessionStorage | react-router |
createSessionStorage | react-router |
The following low-level factory APIs were removed in v7:
createCookieFactorycreateSessionStorageFactorycreateCookieSessionStorageFactorycreateMemorySessionStorageFactorySources:
Cloudflare Workers run in a V8 isolate, which has specific constraints and capabilities compared to Node.js.
Sources:
| Constraint | Impact | Mitigation |
|---|---|---|
| No Node.js APIs | Cannot use fs, path, child_process, etc. | Use Web Standard APIs or Cloudflare-specific bindings |
| CPU Time Limits | Workers have execution time limits | Optimize loader/action performance; use async operations |
| Memory Limits | Limited memory per isolate | Avoid large in-memory data structures; use KV/DO for storage |
| No Native Modules | Cannot use npm packages with native bindings | Use pure JavaScript alternatives |
| Cold Start Latency | First request to an isolate may be slower | Minimize bundle size; optimize imports |
Cloudflare Workers receive environment bindings through the execution context:
These bindings are typically passed to loaders and actions through the context parameter via a getLoadContext function.
Sources:
Sources:
The wrangler CLI is used for deployment to Cloudflare Workers. It is specified as an optional peer dependency:
| Dependency | Version Requirement |
|---|---|
wrangler | ^3.28.2 or ^4.0.0 |
@cloudflare/workers-types | ^4.0.0 |
The Vite plugin requires wrangler as a peer dependency for deployment capabilities.
Sources:
Environment variables in Cloudflare Workers are accessed differently than in Node.js:
Sources:
The integration test suite includes Cloudflare-specific tests to validate edge runtime behavior:
The test template is located in the integration/helpers/cloudflare-dev-proxy-template directory and uses Miniflare for local simulation of the Cloudflare Workers runtime.
Sources:
Refresh this wiki