React Router

Deploy React Router applications to Cloudflare Workers with Alchemy

Deploy React Router applications to Cloudflare Workers with automatic SSR detection and configuration.

Installation

Install the required dependencies:

npm install alchemy react-router @react-router/cloudflare

Configuration

Configuration Options

Properties

• main: Path to workers entry point
  • Default: workers/app.ts
• bindings: Cloudflare bindings (KV, R2, D1, etc.)
• build: Build command override
  • Default: react-router typegen && react-router build
• dev: Dev command override
  • Default: react-router typegen && react-router dev
• entrypoint: Worker entrypoint path
  • Default: build/server/index.js (SSR mode)
• assets: Static assets directory
  • Default: build/client
• spa: Single-page application mode
  • Auto-detected from react-router.config.ts

SSR vs SPA Mode

The resource automatically detects whether SSR is enabled by checking react-router.config.ts:

Server-Side Rendering (Default)

React Router enables SSR by default:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  ssr: true, // default
} satisfies Config;

Client-Side Only

Disable SSR for client-side routing:

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  ssr: false,
} satisfies Config;

Accessing Bindings

Access Cloudflare bindings in your React Router loaders and actions:

Loaders

import type { LoaderFunctionArgs } from "@react-router/cloudflare";

export async function loader({ context }: LoaderFunctionArgs) {
  const db = context.cloudflare.env.DB;
  const result = await db.prepare("SELECT * FROM users").all();
  
  return { users: result.results };
}

Actions

import type { ActionFunctionArgs } from "@react-router/cloudflare";

export async function action({ request, context }: ActionFunctionArgs) {
  const kv = context.cloudflare.env.CACHE;
  const formData = await request.formData();
  
  await kv.put("key", formData.get("value"));
  
  return { success: true };
}

TypeScript Configuration

Generate type-safe bindings with React Router’s type generation:

npm run typegen

This creates types in .react-router/types/ based on your workers/app.ts.

Local Development

The React Router dev server provides:

• Hot module replacement
• Type generation
• Cloudflare Workers emulation

Start the dev server:

npm run dev

Build Configuration

Customize the build process:

const website = await ReactRouter("website", {
  build: "react-router typegen && react-router build --minify",
  dev: {
    command: "react-router typegen && react-router dev --port 3000",
    domain: "localhost:3000",
  },
});

Node.js Compatibility

React Router automatically sets compatibility: "node" for Node.js API support:

• Node.js built-in modules
• npm packages with Node.js dependencies
• Full React Router feature set

Deployment Best Practices

• Keep build/ directory in .gitignore
• Generate types before deploying
• Use environment variables for secrets
• Configure bindings in alchemy.run.ts
• Test locally with React Router dev server

Related Resources

• Website - Base resource for web applications
• Worker - Cloudflare Workers deployment
• D1 Database - SQL database
• KV Namespace - Key-value storage