tRPC: Type-Safe APIs Without Schema Definition

tRPC lets you build fully type-safe APIs by sharing TypeScript types directly between server and client — no code generation, no schema files, no runtime surprises. If your backend changes, TypeScript tells you instantly.

Installation & Project Setup

Install tRPC server, client, React Query integration, and Zod for input validation:

npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query zod

# For Next.js specifically
npm install @trpc/next

Defining Your Router

Create the tRPC instance, define procedures with Zod schemas, and export the router type for the client to import:

// 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;

// server/routers/user.ts
import { router, publicProcedure } from '../trpc';

export const userRouter = router({
  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return db.user.findUnique({ where: { id: input.id } });
    }),

  create: publicProcedure
    .input(z.object({ name: z.string().min(2), email: z.string().email() }))
    .mutation(async ({ input }) => {
      return db.user.create({ data: input });
    }),
});

// server/root.ts — merge all sub-routers
import { router } from './trpc';
import { userRouter } from './routers/user';

export const appRouter = router({ user: userRouter });
export type AppRouter = typeof appRouter;

Next.js App Router Integration

Wire up the tRPC handler as a Next.js API route and create the client-side hook wrapper:

// app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
import { appRouter } from '@/server/root';

const handler = (req: Request) =>
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req,
    router: appRouter,
    createContext: () => ({}),
  });

export { handler as GET, handler as POST };

// utils/trpc.ts — client-side hooks
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '@/server/root';

export const trpc = createTRPCReact<AppRouter>();

// In a component:
// const user = trpc.user.getById.useQuery({ id: '123' });
// const create = trpc.user.create.useMutation();

tRPC vs REST vs GraphQL

Protected Procedures & Middleware

Add authentication by creating a reusable protected procedure via tRPC middleware:

// Extend the context to include session
const t = initTRPC.context<{ session: Session | null }>().create();

// Middleware that throws if not authenticated
const enforceAuth = t.middleware(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({ ctx: { ...ctx, session: ctx.session } });
});

// Reusable protected procedure
export const protectedProcedure = t.procedure.use(enforceAuth);