tRPC (Type-Safe API Layer)

Overview

tRPC enables end-to-end typesafe APIs by sharing TypeScript types between client and server. No code generation, no schema files—just TypeScript.

Version: v11.7+ (2024-2025)

Requirements: TypeScript ≥5.7.2 with strict mode

Key Benefit: Change a procedure's input/output → TypeScript errors appear immediately on client.

When to Use This Skill

✅ Use tRPC when:

• Building full-stack TypeScript apps (Next.js, React + Express)

• You control both client and server code

• Need type-safe API without GraphQL complexity

• Want automatic request batching and caching

• Building internal APIs, dashboards, admin panels

❌ Don't use tRPC when:

• External clients need REST/OpenAPI (use tRPC + OpenAPI adapter)

• Non-TypeScript clients (mobile apps, third-party integrations)

• Microservices with different languages

Quick Start

Installation

npm install @trpc/server @trpc/client zod

For React/Next.js:

npm install @trpc/react-query @tanstack/react-query@^5

Core Setup

Always create tRPC instance in a dedicated file:

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

interface Context { user?: { id: string; role: string }; db: PrismaClient; }

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; export const publicProcedure = t.procedure; export const middleware = t.middleware; export const createCallerFactory = t.createCallerFactory;

Procedure Patterns

Query vs Mutation

// src/server/routers/user.ts import { z } from 'zod'; import { router, publicProcedure, protectedProcedure } from '../trpc'; import { TRPCError } from '@trpc/server';

export const userRouter = router({ // Query - GET semantics (reads) getById: publicProcedure .input(z.object({ id: z.string().uuid() })) .query(async ({ input, ctx }) => { const user = await ctx.db.user.findUnique({ where: { id: input.id } }); if (!user) throw new TRPCError({ code: 'NOT_FOUND' }); return user; }),

// Mutation - POST/PUT/DELETE semantics (writes) create: protectedProcedure .input(z.object({ name: z.string().min(2).max(100), email: z.string().email(), })) .mutation(async ({ input, ctx }) => { return ctx.db.user.create({ data: input }); }), });

Cursor-Based Pagination

list: publicProcedure .input(z.object({ limit: z.number().min(1).max(100).default(10), cursor: z.string().uuid().optional(), })) .query(async ({ input, ctx }) => { const items = await ctx.db.user.findMany({ take: input.limit + 1, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: 'desc' }, });

let nextCursor: string | undefined;
if (items.length > input.limit) {
  nextCursor = items.pop()?.id;
}
return { items, nextCursor };

}),

Middleware Patterns

Authentication Middleware

const isAuthed = middleware(async ({ ctx, next }) => { if (!ctx.user) { throw new TRPCError({ code: 'UNAUTHORIZED' }); } return next({ ctx: { user: ctx.user } }); });

export const protectedProcedure = publicProcedure.use(isAuthed);

Role-Based Authorization

const hasRole = (role: string) => middleware(async ({ ctx, next }) => { if (ctx.user?.role !== role) { throw new TRPCError({ code: 'FORBIDDEN' }); } return next(); });

export const adminProcedure = protectedProcedure.use(hasRole('admin'));

Logging Middleware

const loggerMiddleware = middleware(async ({ path, type, next }) => { const start = Date.now(); const result = await next(); console.log([${type}] ${path} - ${Date.now() - start}ms); return result; });

Context Creation

Express Adapter

// src/server/context.ts import { CreateExpressContextOptions } from '@trpc/server/adapters/express'; import { prisma } from '../lib/prisma';

export async function createContext({ req }: CreateExpressContextOptions) { const token = req.headers.authorization?.split(' ')[1]; const user = token ? await verifyToken(token) : null;

return { user, db: prisma }; }

export type Context = Awaited<ReturnType<typeof createContext>>;

Express Server Setup

// src/server/index.ts import express from 'express'; import cors from 'cors'; import { createExpressMiddleware } from '@trpc/server/adapters/express'; import { appRouter } from './routers/_app'; import { createContext } from './context';

const app = express(); app.use(cors()); app.use('/trpc', createExpressMiddleware({ router: appRouter, createContext, }));

app.listen(3000);

Router Merging

// src/server/routers/_app.ts import { router } from '../trpc'; import { userRouter } from './user'; import { postRouter } from './post';

export const appRouter = router({ user: userRouter, post: postRouter, });

export type AppRouter = typeof appRouter;

Rules

Do ✅

• Use Zod for all input validation

• Create separate routers per domain and merge them

• Use TRPCError with appropriate codes

• Enable strict mode in TypeScript

• Use httpBatchLink on client for request batching

• Export AppRouter type for client

Avoid ❌

• Mixing v10 and v11 patterns (breaking changes)

• Skipping input validation

• Throwing non-TRPCError exceptions (wrap them)

• Creating multiple tRPC instances

• Using any for context types

Error Codes Reference

Code HTTP Use Case

BAD_REQUEST

400 Invalid input

UNAUTHORIZED

401 No/invalid auth

FORBIDDEN

403 No permission

NOT_FOUND

404 Resource missing

CONFLICT

409 Already exists

INTERNAL_SERVER_ERROR

500 Unexpected error

Troubleshooting

"Types not updating on client": → Run TypeScript server in watch mode → Check AppRouter is exported and imported correctly → Verify tsconfig paths match

"Input validation errors not showing": → Add zodError to errorFormatter → Use .safeParse() on client for detailed errors

"CORS errors": → Configure cors() before tRPC middleware → Check origin whitelist

"Procedures not batching": → Ensure using httpBatchLink on client → Check all requests go to same endpoint

File Structure

src/server/ ├── trpc.ts # tRPC instance, base procedures ├── context.ts # Context creation └── routers/ ├── _app.ts # Root router (merges all) ├── user.ts # User procedures └── post.ts # Post procedures

References

• https://trpc.io/docs — Official documentation

• https://trpc.io/docs/client/react — React Query integration

• https://trpc.io/docs/server/adapters — Server adapters