The line between the frontend and the backend has always been a place where types go to die. In a normal REST setup you define the shape of a request and a response on the server, then you write those same shapes again on the client. Nothing keeps the two copies honest. Someone renames a field in the database, the server response changes, and the client keeps trusting the old shape until a runtime error gives it away in production.

Code generation and OpenAPI specs try to close that gap, but they cost you a build step and a pile of config to maintain. tRPC takes a different route: if both sides are TypeScript, they can share the same type directly, so the client and server never drift. No generated code, no schema files, no extra pipeline.

What tRPC is and why teams keep reaching for it

tRPC (TypeScript Remote Procedure Call) is a small framework for building type-safe APIs. The idea is simple: if the server and the client both run TypeScript, they should share one source of truth for their data contracts instead of maintaining two.

It is widely used, with tens of thousands of GitHub stars and millions of weekly downloads, and the reason is that it deletes the translation layer most APIs carry. You do not define HTTP endpoints, schema files, and resolvers. You define backend procedures, which are just functions that validate their input and return data. The frontend then imports the type of those procedures, not the runtime code, and gets autocomplete, strict checking, and an instant compiler error the moment the backend changes.

In a monorepo that feedback loop is immediate. Rename a field on the server and the client component turns red before you even save the file. That is the whole pitch: the network boundary stops being a place where you guess.

How the types actually flow

The part that surprises people is that there is no magic and no generated artifact. The server exports a single type built from its router, and the client imports it. The TypeScript compiler does the rest.

A typical monorepo keeps the router definitions in their own package so server-only code never leaks into the client bundle. The client depends on that package for its types, not its runtime.

How tRPC differs from REST and GraphQL

REST, GraphQL, and tRPC each treat type safety differently, and the differences explain when each one fits.

REST usually gets its types from a spec. You produce an OpenAPI document from the server and run something like openapi-typescript to generate client types. It works, but the safety lives or dies by that build step, and a skipped or broken generation quietly leaves you with a loosely typed boundary again.

GraphQL leans on a strongly typed schema (SDL) and a codegen step (graphql-codegen) to turn that schema into client types. The safety is real, but so is the boilerplate: schema, resolvers, and queries are all written separately.

tRPC skips the schema and the codegen entirely. The server exports a TypeScript type, the client imports it, and the compiler infers everything. There is no step to keep the two sides in sync because they are literally reading the same type.

Setting up a tRPC server

A server needs three things: a context, an initialized tRPC instance, and an HTTP adapter. tRPC ships official adapters for Express, Fastify, the Fetch API (Next.js App Router, edge runtimes), and the plain Node HTTP server.

1
import {db} from './db';
2
import {initTRPC, TRPCError} from '@trpc/server';
3
import type {CreateExpressContextOptions} from '@trpc/server/adapters/express';
4

5
// Runs on every request. Whatever you return here is the `ctx` in procedures.
6
export function createContext({req}: CreateExpressContextOptions) {
7
  const token = req.headers.authorization?.replace('Bearer ', '') ?? null;
8
  return {token, db};
9
}
10

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

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

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

The adapter is the only part that changes between frameworks. Everything above stays identical.

1
import {createContext} from './init';
2
import {appRouter} from './routers/_app';
3
import {createExpressMiddleware} from '@trpc/server/adapters/express';
4
import express from 'express';
5

6
const app = express();
7

8
app.use('/trpc', createExpressMiddleware({router: appRouter, createContext}));
9

10
app.listen(4000, () => console.log('tRPC on http://localhost:4000/trpc'));

1
import {createContext} from '@repo/api/init';
2
import {appRouter} from '@repo/api/routers/_app';
3
import {fetchRequestHandler} from '@trpc/server/adapters/fetch';
4

5
const handler = (req: Request) =>
6
  fetchRequestHandler({
7
    endpoint: '/api/trpc',
8
    req,
9
    router: appRouter,
10
    createContext,
11
  });
12

13
export {handler as GET, handler as POST};

Routers, procedures, and input validation with Zod

A procedure is one endpoint. It is either a query (reads) or a mutation (writes), and procedures are grouped into routers. Input validation is not optional here, and tRPC integrates natively with Zod, which is the community default because its inference lines up perfectly with TypeScript.

When you pass a Zod schema to .input(), tRPC uses it twice. At runtime the server parses the request against the schema and throws if the data is malformed. At compile time it infers the type from the same schema and enforces it on the client, so the client cannot even send the wrong shape.

1
import {router, publicProcedure} from '../init';
2
import {z} from 'zod';
3

4
export const userRouter = router({
5
  // Query: fetching data
6
  getById: publicProcedure
7
    .input(z.object({id: z.string().uuid()}))
8
    .query(async ({input, ctx}) => {
9
      // `input.id` is a validated string by the time we get here.
10
      return ctx.db.user.findUnique(input.id);
11
    }),
12

13
  // Mutation: changing data
14
  create: publicProcedure
15
    .input(z.object({email: z.string().email(), name: z.string().min(2)}))
16
    .mutation(async ({input, ctx}) => {
17
      return ctx.db.user.create(input);
18
    }),
19
});

Individual routers merge into one root router, and that root router is the only thing the frontend needs a type for.

1
import {router} from '../init';
2
import {userRouter} from './user';
3

4
export const appRouter = router({
5
  user: userRouter,
6
});
7

8
// The single type the frontend imports.
9
export type AppRouter = typeof appRouter;

The request lifecycle

It helps to see what a single call actually does on the way through. The client batches the call, the adapter builds a context, middleware runs, Zod validates, and only then does your resolver see the data.

Integrating with React Query on the frontend

tRPC has a first-class integration with TanStack React Query. Version 11 changed how it works. The old approach wrapped React Query in tRPC-specific hooks like trpc.useQuery. The new integration, in @trpc/tanstack-react-query, is query-native: it hands you the queryOptions and mutationOptions that TanStack Query already understands, so you call the standard useQuery and useMutation yourself. Less to learn, and it plays nicely with the React Compiler.

You set up a proxy once:

1
import type {AppRouter} from '@repo/api/routers/_app';
2
import {QueryClient} from '@tanstack/react-query';
3
import {createTRPCClient, httpBatchLink} from '@trpc/client';
4
import {createTRPCOptionsProxy} from '@trpc/tanstack-react-query';
5

6
export const queryClient = new QueryClient();
7

8
const trpcClient = createTRPCClient<AppRouter>({
9
  links: [httpBatchLink({url: 'http://localhost:4000/trpc'})],
10
});
11

12
// Strongly-typed factory for query keys, query options, and mutation options.
13
export const trpc = createTRPCOptionsProxy<AppRouter>({
14
  client: trpcClient,
15
  queryClient,
16
});

Then you use plain TanStack Query hooks in components. The proxy supplies the typed keys, the URL, and the fetching logic.

1
'use client';
2
import {trpc, queryClient} from '../trpc';
3
import {useQuery, useMutation} from '@tanstack/react-query';
4

5
export function UserProfile({userId}: {userId: string}) {
6
  const {data, isLoading, error} = useQuery(
7
    trpc.user.getById.queryOptions({id: userId}),
8
  );
9

10
  const {mutate, isPending} = useMutation(
11
    trpc.user.create.mutationOptions({
12
      onSuccess: () =>
13
        queryClient.invalidateQueries({
14
          queryKey: trpc.user.getById.queryKey(),
15
        }),
16
    }),
17
  );
18

19
  if (isLoading) return <div>Loading...</div>;
20
  if (error) return <div>Error fetching user.</div>;
21

22
  return (
23
    <div>
24
      <h1>{data?.name}</h1>
25
      <button
26
        disabled={isPending}
27
        onClick={() => mutate({email: '[email protected]', name: 'Alice'})}
28
      >
29
        {isPending ? 'Saving...' : 'Create User'}
30
      </button>
31
    </div>
32
  );
33
}

Authentication and middleware

Middleware intercepts a request before it reaches your resolver, which makes it the right home for logging, timing, and authorization. The pattern for auth is to check the context and then extend it with opts.next(), so downstream procedures receive a guaranteed, non-null user.

1
import {verifyToken} from './auth';
2
import {t} from './init';
3
import {TRPCError} from '@trpc/server';
4

5
const isAuthed = t.middleware(async ({ctx, next}) => {
6
  if (!ctx.token) {
7
    throw new TRPCError({code: 'UNAUTHORIZED', message: 'Missing token'});
8
  }
9

10
  const user = await verifyToken(ctx.token);
11
  if (!user) throw new TRPCError({code: 'UNAUTHORIZED'});
12

13
  // Extend the context. From here down, `ctx.user` is guaranteed to exist.
14
  return next({ctx: {user}});
15
});
16

17
export const protectedProcedure = t.procedure.use(isAuthed);

Because the middleware narrows the type, any procedure built on protectedProcedure gets a non-nullable ctx.user with no extra null checks.

1
import {router, protectedProcedure} from '../init';
2

3
export const adminRouter = router({
4
  getDashboardStats: protectedProcedure.query(({ctx}) => {
5
    // TypeScript knows `ctx.user` is defined here.
6
    console.log(`Stats for admin ${ctx.user.id}`);
7
    return {activeUsers: 100, revenue: 5000};
8
  }),
9
});

What is new in v11

tRPC v11 (March 2025) pushed past plain request/response, and these are the additions most teams will actually use.

FormData and file uploads. Procedures can now accept non-JSON content, including FormData and binary types like Blob, File, and Uint8Array. That means real file uploads without a separate REST endpoint.

1
import {router, publicProcedure} from '../init';
2
import {TRPCError} from '@trpc/server';
3
import {z} from 'zod';
4

5
export const uploadRouter = router({
6
  avatar: publicProcedure
7
    .input(z.instanceof(FormData))
8
    .mutation(async ({input}) => {
9
      const file = input.get('file');
10
      if (!(file instanceof File)) {
11
        throw new TRPCError({code: 'BAD_REQUEST', message: 'No file'});
12
      }
13
      // stream `file` to storage here...
14
      return {name: file.name, size: file.size};
15
    }),
16
});

Subscriptions over Server-Sent Events. Real-time updates no longer force you onto WebSockets. Subscriptions are written as async generators, so you yield values over time and clean up naturally when the client disconnects.

1
import {router, publicProcedure} from '../init';
2
import {z} from 'zod';
3

4
export const messageRouter = router({
5
  onMessage: publicProcedure
6
    .input(z.object({roomId: z.string()}))
7
    .subscription(async function* ({input, ctx, signal}) {
8
      // `ctx.bus` is any async iterable event source.
9
      for await (const msg of ctx.bus.subscribe(input.roomId, {signal})) {
10
        yield msg; // pushed to the client over SSE
11
      }
12
    }),
13
});

Streaming queries and mutations. With httpBatchStreamLink, a resolver can return a generator and stream results over plain HTTP, no WebSocket required. Pair it with httpSubscriptionLink for the SSE subscriptions above.

1
import {
2
  createTRPCClient,
3
  httpBatchStreamLink,
4
  httpSubscriptionLink,
5
  splitLink,
6
} from '@trpc/client';
7

8
const trpcClient = createTRPCClient<AppRouter>({
9
  links: [
10
    splitLink({
11
      condition: (op) => op.type === 'subscription',
12
      true: httpSubscriptionLink({url: '/trpc'}),
13
      false: httpBatchStreamLink({url: '/trpc'}),
14
    }),
15
  ],
16
});

Subscriptions also gained output validators in v11, so the values you stream are type-checked the same way inputs are.

When to choose tRPC, GraphQL, or REST

tRPC is not a universal answer. The call comes down to who consumes the API and what language they speak.

Reach for tRPC when you own both ends and they are both TypeScript, usually in a monorepo. Internal dashboards, SaaS products on Next.js or React, and anything where developer speed matters most are where it shines. Dropping schema files and codegen is a real velocity win for a TypeScript-only team.

Stay on REST for public APIs. If your backend has to serve a Swift app, Python microservices, or partner integrations, REST gives you the HTTP semantics, caching, and tooling everyone already supports. Adapters like trpc-openapi can expose REST endpoints from tRPC procedures, but treating REST as an afterthought rarely ends well for heavy public use.

Pick GraphQL for federated microservices or complex clients that need fine-grained control over payloads to avoid over-fetching. Its schema contracts let independent teams work across a big graph and aggregate many systems into one API, which is exactly the problem tRPC does not try to solve.

Frequently Asked Questions

References

• Announcing tRPC v11
• Migrate from v10 to v11
• Introducing the new TanStack React Query integration
• TanStack React Query usage
• tRPC Express adapter
• tRPC Fetch adapter (Next.js / edge)
• Middlewares and context
• Subscriptions
• Zod