React App on Cloudflare Workers with TanStack & tRPC

This project demonstrates a full-stack React application deployed entirely on the Cloudflare edge network, utilizing Cloudflare Workers for the server-side logic and Cloudflare Workers with (Assets) for hosting the static frontend assets.

It leverages the power of the TanStack ecosystem (Query for data fetching/caching, Router for type-safe routing) and tRPC for end-to-end typesafe APIs between the React frontend and the Cloudflare Worker backend.

✨ Features

• React Frontend: Modern UI built with React.
• Cloudflare Workers Backend: Serverless API powered by Cloudflare Workers.
• Cloudflare Pages (Assets) Deployment: Static assets hosted globally on Cloudflare's edge network.
• TanStack Router: Type-safe routing within the React application.
• TanStack Query: Efficient data fetching, caching, and state management.
• tRPC: End-to-end typesafe APIs, eliminating the need for manual API contract maintenance.
• Edge Deployment: Low latency and high availability thanks to Cloudflare's global network.

🛠️ Tech Stack

• Frontend: React, TypeScript, Vite (or Create React App/Next.js configured for static export)
• Routing: TanStack Router
• Data Fetching: TanStack Query
• API: tRPC
• Backend: Cloudflare Workers, Hono (optional, but common for Workers routing)
• Deployment: Cloudflare Pages (Workers integration), Wrangler CLI

🚀 Getting Started

Prerequisites

• Node.js (v18 or later recommended)
• npm or yarn or pnpm
• A Cloudflare account

Installation

Install dependencies: (Depending on your setup, you might have a monorepo structure with packages/client and packages/worker, or a single project. Adjust accordingly.)

npm install
# or
yarn install
# or
pnpm install

Development

1. Start the development server: Typically, you'll run the frontend dev server and the Wrangler dev server concurrently. You might use a tool like concurrently or run them in separate terminals.

   • Frontend with Backend Worker (Vite example):

     # In the client directory or project root
     npm run dev

   Your frontend will likely run on http://localhost:5173 (Vite default) and the worker dev server on http://localhost:8787. Configure your frontend tRPC client to point to the worker's dev URL.

Building

1. Build the frontend:

   # In the client directory or project root
   npm run build

   This will typically generate a dist directory with static assets.

☁️ Deployment to Cloudflare

This project uses Cloudflare Worker as a compute platform

npm run deploy

🔧 Key Concepts

• tRPC Server (Worker): The Cloudflare Worker hosts the tRPC router. It defines procedures (queries and mutations) that the frontend can call.
• tRPC Client (React App): The React app uses the tRPC client, configured with the URL of the deployed Worker (or the dev server URL during development). It provides type-safe hooks (api.post.list.useQuery()) generated from the backend router definition.
• TanStack Query Integration: The tRPC client integrates seamlessly with TanStack Query for caching, request deduplication, background refetching, etc.
• TanStack Router: Manages client-side navigation and state, providing type-safety for route definitions and parameters. It works well with TanStack Query for data fetching tied to specific routes.
• Cloudflare Pages (Assets): Serves the static HTML, CSS, and JavaScript generated by the React build process. Requests to paths not matching static assets can be configured to fall back to the Worker (_worker.js).
• Cloudflare Workers: Executes the server-side tRPC logic. Handles API requests from the frontend.

This setup provides a robust, type-safe, and performant full-stack application running entirely on the Cloudflare edge.