The bug report read: “User creation fails silently on the settings page.” You opened the network tab, found the POST /users call, and the response body said "email": ["expected a valid email address"]. The client code sent email_address (with an underscore). The server expected email (without one). The TypeScript types on the client said email_address: string. The server types said email: string. Both were hand-written. Both compiled. Nothing caught the mismatch except a user staring at an unhelpful error toast.

This kind of bug is the norm in REST and GraphQL codebases, not the exception. You define types on the server. You redefine them on the client. You pray they stay in sync. Sometimes you generate clients from OpenAPI or GraphQL introspection, which helps, but adds a build step, a spec file, and a code generator that can produce its own class of bugs.

tRPC takes a different approach. Instead of defining your API through a schema language and generating types from it, tRPC makes your TypeScript types the schema. The server exports its type. The client imports it. The compiler enforces alignment. If you rename a field on the server, the client build breaks. That is the goal: a compile-time error instead of a production bug.

This post covers a production-grade tRPC setup with authentication, structured error handling, middleware, request validation, and rate limiting. By the end, you will have a working server and client that share types without a build step, a spec file, or a code generator.

The mental model

tRPC is not a framework. It is a function call that happens over HTTP. Every procedure on the server is a plain TypeScript function. Every call from the client is a typed function invocation. The transport layer is HTTP POST under the hood, but you never touch req, res, or fetch directly.

The key insight is that tRPC uses TypeScript’s type inference to encode the API contract. The server defines a router object. The client creates a proxy from the router’s type. At runtime, the client calls a function, tRPC serializes the arguments as JSON over HTTP, the server deserializes them, runs the function, and sends the result back as JSON. On the client, the return type is the server’s TypeScript return type, inferred at compile time through the proxy.

No OpenAPI file. No code generator. No hand-written fetch wrappers. The compiler is your contract validator.

Bootstrapping the server

Start with the server. Install the core packages:

npm install @trpc/server @trpc/client zod

Define a simple router with one procedure:

// src/server/trpc.ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const router = t.router;
export const publicProcedure = t.procedure;

// src/server/index.ts
import { z } from 'zod';
import { router, publicProcedure } from './trpc';

const appRouter = router({
  greet: publicProcedure
    .input(z.object({ name: z.string().min(1) }))
    .query(({ input }) => {
      return { message: `Hello, ${input.name}!` };
    }),
  createUser: publicProcedure
    .input(z.object({
      email: z.string().email(),
      name: z.string().min(1),
    }))
    .mutation(async ({ input }) => {
      // In real code, insert into the database
      const user = { id: crypto.randomUUID(), ...input };
      return user;
    }),
});

export type AppRouter = typeof appRouter;

The router distinguishes between queries (GET-like, idempotent) and mutations (POST-like, state-changing). Both accept Zod schemas for input validation. If the client sends an invalid name, Zod throws before the handler runs, and tRPC returns a structured validation error.

Now wire up the HTTP server. The recommended adapter for Node.js is Fastify, but Express works too:

// src/server/http.ts
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './index';

const server = createHTTPServer({
  router: appRouter,
  createContext() {
    return {}; // We will fill this in with auth
  },
});

server.listen(3000);
console.log('Server running on http://localhost:3000');

That is the entire server. Sixteen lines of application code, and you have a typed API endpoint. No routing config, no middleware stack for JSON parsing, no manual error handling for invalid input.

The client

On the client side, install the client package:

npm install @trpc/client

Import the type from the server:

// src/client.ts
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '../server/index';

const client = createTRPCProxyClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:3000' })],
});

// Fully typed, no code generation needed
const result = await client.greet.query({ name: 'Alice' });
console.log(result.message); // "Hello, Alice!"

const user = await client.createUser.mutate({
  email: 'alice@example.com',
  name: 'Alice',
});
console.log(user.id);

If you rename name to firstName in the server’s Zod schema, the client file will not compile until you update the call site. That is the entire value proposition. No runtime surprises.

The httpBatchLink automatically batches multiple requests made within a short time window into a single HTTP call. This is significant for performance: rendering a dashboard that calls five procedures does not result in five round trips. tRPC coalesces them into one HTTP request with an array of inputs and returns an array of outputs. The client API remains async function calls. The batching is transparent.

Authentication with context

Public procedures are rare in production. Most endpoints need to know who is calling them. tRPC handles this through context, a per-request object you populate in the adapter’s createContext function and access in every procedure.

First, add a context creator that extracts and verifies a token:

// src/server/context.ts
import { inferAsyncReturnType } from '@trpc/server';
import { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';

export async function createContext({ req, res }: CreateFastifyContextOptions) {
  // Extract the Authorization header
  const header = req.headers.authorization;
  const token = header?.startsWith('Bearer ') ? header.slice(7) : null;

  // Verify the token. This is a placeholder; use JWT or your auth provider.
  let user: { id: string; role: string } | null = null;
  if (token) {
    // verifyJwt(token) returns decoded payload or throws
    user = { id: 'user_123', role: 'admin' };
  }

  return { user, req, res };
}

export type Context = inferAsyncReturnType<typeof createContext>;

Then update the tRPC initialization to use the context type:

// src/server/trpc.ts
import { initTRPC } from '@trpc/server';
import type { Context } from './context';

const t = initTRPC.context<Context>().create();

export const router = t.router;
export const publicProcedure = t.procedure;

Now create an authenticated procedure that rejects unauthenticated requests:

// src/server/trpc.ts (continued)
import { TRPCError } from '@trpc/server';

const isAuthenticated = t.middleware(({ ctx, next }) => {
  if (!ctx.user) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'You must be logged in to access this resource',
    });
  }
  return next({
    ctx: { user: ctx.user },
  });
});

export const protectedProcedure = t.procedure.use(isAuthenticated);

Use protectedProcedure anywhere you need authentication:

// src/server/index.ts
const appRouter = router({
  getProfile: protectedProcedure
    .query(({ ctx }) => {
      return { id: ctx.user.id, role: ctx.user.role };
    }),
  deleteUser: protectedProcedure
    .input(z.object({ userId: z.string() }))
    .mutation(async ({ ctx, input }) => {
      if (ctx.user.role !== 'admin') {
        throw new TRPCError({
          code: 'FORBIDDEN',
          message: 'Only admins can delete users',
        });
      }
      // Delete the user from the database
    }),
});

The middleware pattern composes cleanly. Add a logging middleware, a rate-limiting middleware, or a tenant-isolation middleware with the same t.middleware() API. Each middleware can augment the context for downstream procedures.

Structured error handling

The TRPCError class maps to standard HTTP status codes:

Code	HTTP Status	When to use
PARSE_ERROR	400	Malformed request body
BAD_REQUEST	400	Validation failure (Zod handles this automatically)
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Authenticated but not allowed
NOT_FOUND	404	Resource does not exist
TIMEOUT	408	Procedure took too long
CONFLICT	409	Duplicate resource, version conflict
PRECONDITION_FAILED	412	Business rule violation
PAYLOAD_TOO_LARGE	413	Input exceeds limit
METHOD_NOT_SUPPORTED	405	Wrong procedure type
TOO_MANY_REQUESTS	429	Rate limited
CLIENT_CLOSED_REQUEST	499	Client disconnected
INTERNAL_SERVER_ERROR	500	Unexpected error

On the client, you catch these with standard try/catch:

import { TRPCClientError } from '@trpc/client';

try {
  await client.deleteUser.mutate({ userId: 'user_456' });
} catch (error) {
  if (error instanceof TRPCClientError) {
    console.error(error.message); // "Only admins can delete users"
    console.error(error.data.code); // "FORBIDDEN"
    console.error(error.data.httpStatus); // 403
  }
}

No parsing the response body. No checking error.response.status. The type system already knows what the error looks like.

Request validation beyond basic types

Zod schemas inline in procedure definitions work well for simple cases. For complex mutations, extract the schema into a separate file and reuse it in tests:

// src/schemas/user.ts
import { z } from 'zod';

export const createUserSchema = z.object({
  email: z.string().email('Must be a valid email address'),
  name: z.string().min(1, 'Name is required').max(100),
  role: z.enum(['user', 'admin', 'moderator']).default('user'),
  metadata: z.record(z.string()).optional(),
});

export type CreateUserInput = z.infer<typeof createUserSchema>;

// src/server/index.ts
import { createUserSchema } from '../schemas/user';

const appRouter = router({
  createUser: protectedProcedure
    .input(createUserSchema)
    .mutation(async ({ ctx, input }) => {
      // input is fully typed as CreateUserInput
    }),
});

Zod handles coercion, defaults, and refinements. Need to validate that a date range starts before it ends? Add a .refine():

const dateRangeSchema = z.object({
  start: z.coerce.date(),
  end: z.coerce.date(),
}).refine(data => data.start < data.end, {
  message: 'Start date must be before end date',
  path: ['start'],
});

All of these errors surface through tRPC’s standard error format. The client does not need special parsing logic for business rule violations.

Rate limiting with middleware

Add rate limiting as a reusable middleware:

// src/server/rateLimit.ts
import { TRPCError } from '@trpc/server';
import { t } from './trpc';

// Simple in-memory rate limiter; use Redis in production
const rateMap = new Map<string, { count: number; resetAt: number }>();

export const rateLimit = t.middleware(({ ctx, next, path }) => {
  const key = ctx.user?.id ?? ctx.req.ip;
  const now = Date.now();
  const windowMs = 60_000; // 1 minute
  const maxRequests = 100;

  const entry = rateMap.get(key);
  if (!entry || entry.resetAt < now) {
    rateMap.set(key, { count: 1, resetAt: now + windowMs });
    return next();
  }

  if (entry.count >= maxRequests) {
    throw new TRPCError({
      code: 'TOO_MANY_REQUESTS',
      message: 'Rate limit exceeded. Try again in 60 seconds.',
    });
  }

  entry.count++;
  return next();
});

export const rateLimitedProcedure = t.procedure.use(isAuthenticated).use(rateLimit);

Use rateLimitedProcedure for expensive endpoints like user creation or file upload.

Request batching and cache headers

tRPC’s httpBatchLink sends multiple queries in a single HTTP POST. This is great for performance but interacts poorly with HTTP caching proxies (CDNs, browser cache). Since batched requests use POST, they bypass most HTTP caches by default.

For read-heavy workloads where caching matters, use a separate httpLink (no batching) for queries that should be cacheable, and httpBatchLink for everything else. Configure the server to emit Cache-Control headers on individual queries:

// This requires a custom response in the context
// or using Fastify's reply object directly

Or use httpBatchLink for mutations and splitLink to route queries differently:

import { createTRPCProxyClient, httpBatchLink, httpLink, splitLink } from '@trpc/client';

const client = createTRPCProxyClient<AppRouter>({
  links: [
    splitLink({
      condition: (op) => op.type === 'query',
      true: httpLink({ url: 'http://localhost:3000' }),
      false: httpBatchLink({ url: 'http://localhost:3000' }),
    }),
  ],
});

This sends queries as individual GET requests (cacheable) and mutations as batched POSTs. You get the caching benefit for reads and the batching benefit for writes.

Error handling on the client

Every React project using tRPC should have an error boundary or a hook wrapper that surfaces server errors to users. tRPC provides @trpc/react-query for React integration, which wraps React Query under the hood. Here is a minimal React setup:

import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/index';

export const trpc = createTRPCReact<AppRouter>();

function MyComponent() {
  const greeting = trpc.greet.useQuery({ name: 'Alice' });
  const createUser = trpc.createUser.useMutation();

  if (greeting.error) {
    return <div>Error: {greeting.error.message}</div>;
  }

  return (
    <div>
      <p>{greeting.data?.message}</p>
      <button onClick={() => createUser.mutate({ email: 'a@b.com', name: 'Alice' })}>
        Create
      </button>
    </div>
  );
}

React Query handles caching, retries, and stale data automatically. The useMutation hook exposes isLoading, error, and data states. You never serialize or deserialize a request manually.

The real trade-offs

tRPC is not universally better than REST or GraphQL. Here is what you give up:

No HTTP caching on most endpoints. tRPC uses POST by default. If your API serves millions of requests for the same data each day (a public read-only API), REST with GET and Cache-Control headers will outperform tRPC at the CDN level. The splitLink workaround above helps but adds complexity.

No public API documentation. There is no tRPC equivalent of Swagger UI. Third-party developers cannot open a browser and explore your API. tRPC is designed for first-party clients (your frontend, your mobile app, your internal services). If your API is public, stick with OpenAPI.

Tight coupling between server and client. This is the feature, not a bug, but it means the server and client must be in the same monorepo or share a package. Separate teams with separate deploy cadences will find the tight coupling painful.

WebSocket streaming is possible but not native. tRPC supports subscriptions via @trpc/server subscriptions, but the implementation is less mature than GraphQL subscriptions or raw WebSocket handlers.

Use tRPC when you control both ends of the API and want maximum type safety with minimum boilerplate. Use REST or GraphQL when you need caching, public documentation, or decoupled teams.

The production checklist

Before deploying tRPC to production, verify these points:

• Middleware order: authentication before authorization before rate limiting.
• Context is populated from the correct adapter (Fastify, Express, Next.js).
• Error messages do not leak internal details in production (use t.procedure with custom error formatting).
• batching is configured with maxBatchSize to prevent 50 KB request bodies.
• The server adapter is behind your existing HTTPS and TLS termination.
• Zod schemas are tested independently, not just through e2e tests.
• File uploads use a separate endpoint or FormData, not tRPC (tRPC expects JSON).

The 60-line production server

Here is everything above combined into a server you can deploy:

import { initTRPC, TRPCError } from '@trpc/server';
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { z } from 'zod';

// --- Context ---
async function createContext({ req }: { req: Request }) {
  const token = req.headers.get('authorization')?.slice(7);
  const user = token ? { id: 'user_123', role: 'admin' } : null;
  return { user, req };
}
type Context = { user: { id: string; role: string } | null; req: Request };

// --- tRPC instance ---
const t = initTRPC.context<Context>().create();

// --- Middleware ---
const authMiddleware = t.middleware(({ ctx, next }) => {
  if (!ctx.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
  return next({ ctx: { user: ctx.user } });
});

// --- Schemas ---
const userSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

// --- Router ---
const appRouter = t.router({
  hello: t.procedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => `Hello, ${input.name}`),
  me: t.procedure.use(authMiddleware)
    .query(({ ctx }) => ({ id: ctx.user.id, role: ctx.user.role })),
  createUser: t.procedure.use(authMiddleware)
    .input(userSchema)
    .mutation(async ({ input }) => {
      // Insert into database
      return { id: crypto.randomUUID(), ...input };
    }),
});

export type AppRouter = typeof appRouter;

// --- HTTP ---
const server = createHTTPServer({
  router: appRouter,
  createContext,
});
server.listen(3000);

And the client:

import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCProxyClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:3000' })],
});

const greeting = await client.hello.query({ name: 'Alice' });
const user = await client.createUser.mutate({
  email: 'alice@example.com',
  name: 'Alice',
});

Two files. Zero hand-written fetch calls. Zero type files to keep in sync. If this code compiles, the server and client agree on every field name, every type, and every optionality constraint. That is the entire point.

A note from Yojji

Building an API layer that eliminates entire categories of bugs at compile time is exactly the kind of engineering investment that pays for itself within the first few sprints. Yojji’s teams apply this same discipline to the full-stack applications they build, from TypeScript monorepos to cloud-native deployments, ensuring that type safety and production reliability are designed in from the start rather than bolted on after the fact.

Yojji is an international custom software development company founded in 2016, with offices in Europe, the US, and the UK. Their senior engineering teams specialize in the JavaScript ecosystem (React, Node.js, TypeScript), cloud platforms (AWS, Azure, GCP), and full-cycle product engineering, including the API architecture and validation patterns that keep production systems stable.