Rork Max × tRPC × Cloudflare Workers: Designing, Implementing, and Running a Type-Safe Edge API Backend

Why Cloudflare Workers Is the Right Choice Here

Edge Execution: What It Actually Means

Cloudflare Workers doesn't run your code in a single data center. It deploys your code to Cloudflare's network of 300+ data centers worldwide and executes each request at the location closest to the user making it. This is fundamentally different from traditional serverless functions like AWS Lambda, where your function runs in one region and adds latency for users elsewhere.

For a Rork Max app targeting a global audience, this difference is significant. A user in Tokyo calling your API doesn't need to wait for a round trip to a data center in US-East. Their request hits a Cloudflare data center in or near Japan and gets a response in milliseconds. This is what "edge computing" means in practice.

No Cold Starts

AWS Lambda and Google Cloud Functions suffer from cold starts: the first request after a period of inactivity can take several hundred milliseconds to a few seconds while the runtime initializes. Cloudflare Workers doesn't have this problem because it uses V8 isolates rather than full VMs or containers. Your code is always warm. For a mobile app where users expect instant feedback, eliminating cold starts noticeably improves the experience.

The Economics for Indie Developers

Cloudflare Workers' free tier is genuinely generous: 100,000 requests per day, 10ms CPU time per request, and access to KV storage with 100,000 reads and 1,000 writes per day. For most apps at the indie stage, this is enough to run indefinitely without paying anything. The paid Workers Paid plan is $5/month and adds 10 million requests per month and 30ms CPU time — enough to handle a modestly successful app with tens of thousands of daily active users.

Compare this to running even the smallest EC2 instance or a managed Postgres database, and the cost difference is stark. This stack lets you launch a production-quality backend for free and only start paying when you have meaningful revenue to justify it.

Environment Setup and Project Architecture

Choosing a Monorepo Structure

The key to making tRPC work is sharing the AppRouter type between packages. The cleanest way to achieve this in a Rork Max project is a monorepo managed with pnpm workspaces. You have your mobile app in apps/mobile and your API in packages/api. The mobile app imports only the TypeScript type from the API package — no runtime code crosses the boundary.

my-rork-app/
├── apps/
│   └── mobile/        ← Rork Max project
│       ├── app/
│       ├── package.json
│       └── ...
├── packages/
│   └── api/           ← tRPC backend (Cloudflare Workers)
│       ├── src/
│       │   ├── index.ts       ← Workers entry point
│       │   ├── router/        ← tRPC router definitions
│       │   ├── middleware/    ← Auth, logging middleware
│       │   └── db/            ← D1 / Supabase integration
│       ├── wrangler.toml
│       └── package.json
├── package.json       ← Workspace root
└── pnpm-workspace.yaml

Your pnpm-workspace.yaml is simply:

packages:
  - 'apps/*'
  - 'packages/*'

This lets you run pnpm install from the root and have dependencies installed across all packages efficiently.

Installing Dependencies

# Backend package
cd packages/api
pnpm add @trpc/server hono @hono/trpc-server zod jose
pnpm add -D wrangler @cloudflare/workers-types typescript
 
# Rork Max (mobile) side
cd apps/mobile
pnpm add @trpc/client @trpc/react-query @tanstack/react-query zod

The jose library handles JWT signing and verification in Workers (native browser crypto API). We use Hono as a lightweight wrapper around the Workers fetch handler because it makes CORS configuration, logging, and route grouping much cleaner than raw Workers code.

Configuring wrangler.toml

# packages/api/wrangler.toml
name = "my-rork-api"
main = "src/index.ts"
compatibility_date = "2026-03-01"
compatibility_flags = ["nodejs_compat"]
 
[vars]
ENVIRONMENT = "production"
 
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"
 
[[d1_databases]]
binding = "DB"
database_name = "my-rork-db"
database_id = "your-database-id"

The nodejs_compat flag is essential — tRPC and jose rely on Node.js built-ins like crypto that aren't available in the default Workers runtime. This flag adds compatibility polyfills for those modules.

Building the tRPC Router Layer

Initializing tRPC and Defining Context

Context is what makes tRPC procedures aware of their environment. Your context contains the Cloudflare environment bindings (D1 database, KV namespace, secrets) and any per-request data like the authenticated user ID. You define it once and every procedure has access to it through the ctx parameter.

// packages/api/src/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';
 
export interface Context {
  env: Env;
  userId?: string;
}
 
const t = initTRPC.context<Context>().create({
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError:
          error.cause instanceof z.ZodError
            ? error.cause.flatten()
            : null,
      },
    };
  },
});
 
export const router = t.router;
 
// Open to everyone
export const publicProcedure = t.procedure;
 
// Requires a valid JWT — throws UNAUTHORIZED otherwise
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.userId) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'Authentication required',
    });
  }
  return next({ ctx: { ...ctx, userId: ctx.userId } });
});

The errorFormatter ensures that Zod validation errors are surfaced to the client in a structured, queryable format. When input validation fails, the client receives error.data.zodError.fieldErrors — an object mapping each invalid field to its error messages. This lets your Rork Max form components show precise, field-level errors without any additional error parsing logic.

Root Router Composition

Organizing your router by domain keeps each file focused and testable. The root router simply composes them:

// packages/api/src/router/index.ts
import { router } from '../trpc';
import { authRouter } from './auth';
import { userRouter } from './user';
import { contentRouter } from './content';
 
export const appRouter = router({
  auth: authRouter,
  user: userRouter,
  content: contentRouter,
});
 
export type AppRouter = typeof appRouter;

A Well-Designed User Router

Here's a user router that demonstrates the full range of tRPC patterns: schema definition with Zod, output type contracts, database queries via D1, and proper error handling:

// packages/api/src/router/user.ts
import { z } from 'zod';
import { router, protectedProcedure, publicProcedure } from '../trpc';
import { TRPCError } from '@trpc/server';
 
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(50),
  email: z.string().email(),
  bio: z.string().max(200).optional(),
  avatarUrl: z.string().url().optional(),
  createdAt: z.string(),
});
 
export const userRouter = router({
  getProfile: publicProcedure
    .input(z.object({ userId: z.string().uuid() }))
    .output(UserSchema)
    .query(async ({ input, ctx }) => {
      const result = await ctx.env.DB.prepare(
        'SELECT * FROM users WHERE id = ?'
      ).bind(input.userId).first();
 
      if (!result) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: 'User not found',
        });
      }
 
      return result as z.infer<typeof UserSchema>;
    }),
 
  updateProfile: protectedProcedure
    .input(z.object({
      name: z.string().min(1).max(50).optional(),
      bio: z.string().max(200).optional(),
    }))
    .mutation(async ({ input, ctx }) => {
      const updates: string[] = [];
      const values: unknown[] = [];
 
      if (input.name) { updates.push('name = ?'); values.push(input.name); }
      if (input.bio !== undefined) { updates.push('bio = ?'); values.push(input.bio); }
 
      if (updates.length === 0) {
        throw new TRPCError({ code: 'BAD_REQUEST', message: 'No fields to update' });
      }
 
      values.push(new Date().toISOString(), ctx.userId);
 
      await ctx.env.DB.prepare(
        `UPDATE users SET ${updates.join(', ')}, updated_at = ? WHERE id = ?`
      ).bind(...values).run();
 
      return { success: true };
    }),
});

Defining both .input() and .output() on a procedure is a useful discipline for premium APIs. The output schema acts as a contract: if your database query returns a shape that doesn't match UserSchema, you'll get a runtime error in development before it reaches production.

The Cloudflare Workers Entry Point

Hono + tRPC Integration

Hono is a lightweight web framework for Cloudflare Workers. Its @hono/trpc-server package provides a middleware that bridges tRPC and Hono's request handling. The combination is cleaner than writing raw Workers fetch handlers because Hono gives you composable middleware for CORS, logging, and route grouping.

// packages/api/src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';
import { trpcServer } from '@hono/trpc-server';
import { appRouter } from './router';
import { createContext } from './context';
 
export interface Env {
  DB: D1Database;
  CACHE: KVNamespace;
  JWT_SECRET: string;
  ENVIRONMENT: string;
}
 
const app = new Hono<{ Bindings: Env }>();
 
app.use('/trpc/*', cors({
  origin: ['https://your-rork-app.com', 'exp://localhost:8081'],
  allowMethods: ['GET', 'POST', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
}));
 
app.use('/trpc/*', logger());
 
app.use('/trpc/*', trpcServer({
  router: appRouter,
  createContext: async (opts, c) => createContext(opts, c),
}));
 
app.get('/health', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString() }));
 
export default app;

JWT Authentication in Context

The context creation function runs on every request and is where you extract and verify the JWT token. The important design choice here is that an invalid or missing token doesn't throw — it simply leaves userId as undefined. Protected procedures will then reject unauthorized requests. This allows a single entry point to serve both public and protected procedures without route-level auth guards.

// packages/api/src/context.ts
import { FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';
import type { Context } from 'hono';
import type { Env } from './index';
import * as jose from 'jose';
 
export async function createContext(
  opts: FetchCreateContextFnOptions,
  c: Context<{ Bindings: Env }>
) {
  const authHeader = opts.req.headers.get('Authorization');
  let userId: string | undefined;
 
  if (authHeader?.startsWith('Bearer ')) {
    const token = authHeader.slice(7);
    try {
      const secret = new TextEncoder().encode(c.env.JWT_SECRET);
      const { payload } = await jose.jwtVerify(token, secret);
      userId = payload.sub as string;
    } catch {
      // Invalid or expired token — proceed as unauthenticated
    }
  }
 
  return { env: c.env, userId };
}

Building the Rork Max Client

Initializing the tRPC Client

The crucial step here is importing AppRouter as a type-only import. This ensures no backend code ends up in your mobile bundle — you're importing only the TypeScript shape, which the compiler strips entirely at build time.

// apps/mobile/src/lib/trpc.ts
import { createTRPCReact } from '@trpc/react-query';
import { httpBatchLink } from '@trpc/client';
import type { AppRouter } from '../../../packages/api/src/router';
 
export const trpc = createTRPCReact<AppRouter>();
 
export function createTRPCClient(getToken: () => string | null) {
  return {
    links: [
      httpBatchLink({
        url: process.env.EXPO_PUBLIC_API_URL + '/trpc',
        headers() {
          const token = getToken();
          return token ? { Authorization: `Bearer ${token}` } : {};
        },
      }),
    ],
  };
}

The httpBatchLink automatically batches multiple tRPC calls that happen in the same render cycle into a single HTTP request. This is a significant performance win for screens that need to fetch several pieces of data simultaneously — instead of three separate round trips, you make one.

Setting Up React Query Provider

tRPC uses React Query under the hood for caching, refetching, and loading state management. You need to provide both a QueryClient and the trpc provider:

// apps/mobile/src/providers/TRPCProvider.tsx
import { useState } from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { trpc, createTRPCClient } from '../lib/trpc';
import { useAuth } from '../hooks/useAuth';
 
export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const { getToken } = useAuth();
 
  const [queryClient] = useState(() =>
    new QueryClient({
      defaultOptions: {
        queries: { retry: 2, staleTime: 5 * 60 * 1000 }, // 5-minute cache
      },
    })
  );
 
  const [trpcClient] = useState(() =>
    trpc.createClient(createTRPCClient(getToken))
  );
 
  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </trpc.Provider>
  );
}

Wrap your root layout with TRPCProvider and every screen in your app can immediately start using tRPC hooks with full type safety.

Using tRPC in Screens

Here's how data fetching and mutations look in a real screen component:

// apps/mobile/src/screens/ProfileScreen.tsx
import { View, Text, TextInput, TouchableOpacity, ActivityIndicator } from 'react-native';
import { useState } from 'react';
import { trpc } from '../lib/trpc';
 
export function ProfileScreen({ userId }: { userId: string }) {
  const [newBio, setNewBio] = useState('');
  const utils = trpc.useUtils();
 
  // Fully typed query — profile's shape is inferred from AppRouter
  const { data: profile, isLoading, error } = trpc.user.getProfile.useQuery(
    { userId },
    { enabled: !!userId }
  );
 
  // Typed mutation with cache invalidation
  const updateProfile = trpc.user.updateProfile.useMutation({
    onSuccess: () => {
      utils.user.getProfile.invalidate({ userId });
    },
    onError: (err) => {
      if (err.data?.zodError) {
        console.error('Validation errors:', err.data.zodError.fieldErrors);
      }
    },
  });
 
  if (isLoading) return <ActivityIndicator />;
  if (error) return <Text>Error: {error.message}</Text>;
 
  return (
    <View>
      <Text>{profile.name}</Text>
      <Text>{profile.email}</Text>
      <TextInput
        value={newBio}
        onChangeText={setNewBio}
        placeholder="Update bio"
      />
      <TouchableOpacity
        onPress={() => updateProfile.mutate({ bio: newBio })}
        disabled={updateProfile.isPending}
      >
        <Text>Save</Text>
      </TouchableOpacity>
    </View>
  );
}

Notice that you never had to define types for profile. TypeScript infers them directly from your server-side UserSchema via AppRouter. If you add a field to the user profile on the server, it immediately appears as a typed property here. If you remove a field, any client code accessing that field becomes a compile error.

Advanced Production Patterns

Database Schema and Migrations with D1

Cloudflare D1 is a SQLite-compatible database that runs at the edge alongside your Workers code. Define your schema in SQL migration files and manage them with Wrangler:

-- packages/api/src/db/migrations/0001_create_users.sql
CREATE TABLE IF NOT EXISTS users (
  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  bio TEXT,
  avatar_url TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);
 
CREATE INDEX idx_users_email ON users(email);

# Create and apply migrations
npx wrangler d1 create my-rork-db
npx wrangler d1 migrations apply my-rork-db --local  # Local dev
npx wrangler d1 migrations apply my-rork-db           # Production

D1 queries are simple: prepare a parameterized statement with .prepare(), bind values with .bind(), and execute with .first() (one row), .all() (all rows), or .run() (mutations).

KV Caching for High-Read Data

Not every piece of data needs to hit the database on every request. Featured content, configuration, and computed aggregates are good candidates for KV caching. A simple wrapper function makes the pattern reusable:

// packages/api/src/utils/cache.ts
export async function withCache<T>(
  kv: KVNamespace,
  key: string,
  ttlSeconds: number,
  fetcher: () => Promise<T>
): Promise<T> {
  const cached = await kv.get(key, 'json');
  if (cached !== null) return cached as T;
 
  const fresh = await fetcher();
  await kv.put(key, JSON.stringify(fresh), { expirationTtl: ttlSeconds });
  return fresh;
}
 
// In a router — transparent caching of expensive queries
export const contentRouter = router({
  getFeaturedContent: publicProcedure.query(async ({ ctx }) => {
    return withCache(ctx.env.CACHE, 'featured-content', 300, async () =>
      ctx.env.DB.prepare(
        'SELECT * FROM content WHERE featured = 1 ORDER BY created_at DESC LIMIT 10'
      ).all()
    );
  }),
});

Five-minute caching of featured content means the database is queried at most twelve times per hour for that data, regardless of how many users hit the endpoint simultaneously.

Middleware for Rate Limiting

For procedures that could be abused — like authentication endpoints or content generation — add rate limiting via tRPC middleware:

// packages/api/src/middleware/rateLimit.ts
import { TRPCError } from '@trpc/server';
import { t } from '../trpc';
 
export const rateLimitMiddleware = t.middleware(async ({ ctx, next, path }) => {
  const ip = 'client-ip'; // In practice, read from CF-Connecting-IP header
  const key = `rate-limit:${ip}:${path}`;
  const limit = 60;
 
  const current = await ctx.env.CACHE.get(key);
  const count = current ? parseInt(current) : 0;
 
  if (count >= limit) {
    throw new TRPCError({
      code: 'TOO_MANY_REQUESTS',
      message: 'Rate limit exceeded. Please try again in a minute.',
    });
  }
 
  await ctx.env.CACHE.put(key, String(count + 1), { expirationTtl: 60 });
  return next();
});
 
// Apply to a procedure
export const rateLimitedProcedure = publicProcedure.use(rateLimitMiddleware);

tRPC middleware composes cleanly. You can combine rate limiting, authentication, and logging into a single procedure type by chaining .use() calls.

Troubleshooting Common Issues

CORS Errors in Expo Development

When running your Rork Max app in Expo Go or the Expo development server, requests originate from exp://localhost:8081 or a local network IP. Make sure your Hono CORS configuration explicitly allows these origins. In production Expo builds (standalone apps), requests come from the device's network stack without an Origin header, so you may not see CORS issues at all — but it's worth testing with a standalone build before assuming the configuration is correct.

Workers Fails to Start with nodejs_compat

If you see errors about missing Node.js modules like crypto or buffer, ensure compatibility_flags = ["nodejs_compat"] is present in your wrangler.toml. Without it, any npm package that internally uses Node.js built-ins will fail at startup.

Type Inference Broken After Adding a New Procedure

The most common cause is a circular import. If your new router file imports from a file that (directly or indirectly) imports from the router itself, TypeScript's type inference can break. Keep your router files import-clean: routers import from ../trpc and utility modules, never from other routers or the root index.ts.

D1 Query Returns Unexpected Column Names

Cloudflare D1 returns column names exactly as they appear in the database schema. If your schema uses avatar_url (snake_case) but your TypeScript type expects avatarUrl (camelCase), the Zod parse will fail. Either normalize column names in SQL using AS aliases (SELECT avatar_url AS avatarUrl FROM users) or transform the result in the query handler before returning.

CI/CD Pipeline with GitHub Actions

Automating deployment removes the risk of forgetting a step, ensures migrations always run before new code deploys, and gives you a deployment audit trail through GitHub Actions history.

# .github/workflows/deploy-api.yml
name: Deploy API to Cloudflare Workers
 
on:
  push:
    branches: [main]
    paths:
      - 'packages/api/**'
      - '.github/workflows/deploy-api.yml'
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: pnpm/action-setup@v2
        with:
          version: 9
 
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
 
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
 
      - name: Run TypeScript checks
        run: pnpm --filter api tsc --noEmit
 
      - name: Run D1 migrations
        working-directory: packages/api
        run: npx wrangler d1 migrations apply my-rork-db
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 
      - name: Deploy to Cloudflare Workers
        working-directory: packages/api
        run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Add CLOUDFLARE_API_TOKEN (generated from the Cloudflare dashboard under API Tokens with Workers and D1 permissions) and CLOUDFLARE_ACCOUNT_ID to your repository's Secrets. From that point on, every merge to main that touches the API package automatically runs type checks, applies migrations, and deploys to the global edge network.

For even more confidence, add a staging environment by creating a second wrangler.toml environment block and a separate GitHub Actions job that deploys to staging on pull requests, with production deployment gated on merge to main.

A Note from an Indie Developer

Key Takeaways

The Rork Max × tRPC × Cloudflare Workers stack represents one of the most compelling full-stack architectures available to indie mobile developers in 2026. End-to-end type safety means the most common class of API bugs — mismatched types, renamed fields, changed response shapes — are caught by the compiler before they ever reach users. Cloudflare Workers' global edge execution means your users get low-latency responses regardless of where they are. And the economics make it realistic to launch and run a production backend for free until your app achieves meaningful scale.

The learning curve is real, particularly around monorepo tooling and Cloudflare Workers' environment model. But once the foundation is in place, the development velocity that comes from complete end-to-end type safety is genuinely transformative. You spend less time writing interface files, less time debugging mismatched data shapes, and more time building features your users actually want.

Start with a single router and a few procedures. Add authentication. Then caching. Then CI/CD. Each layer builds naturally on the previous one. Within a week of following this guide, you'll have a globally distributed, type-safe API backend running in production — and a development workflow that makes you genuinely reluctant to build any other way.