tRPC — End-to-End Typesafe APIs for TypeScript

What tRPC Does

• End-to-End Types: Share TypeScript types between client and server automatically
• No Schema: No protobuf, GraphQL schemas, or OpenAPI to maintain
• Input Validation: Built-in Zod/Yup/Valibot validation
• Subscriptions: WebSocket support for real-time updates
• Middleware: Reusable logic for auth, logging, rate limiting
• Error Handling: Typed error responses
• Batching: Automatic request batching to reduce round-trips
• Framework Support: Next.js, Express, Fastify, AWS Lambda, Cloudflare Workers
• Client Support: React, Vue, vanilla TS, Svelte, SolidJS
• Streaming: Server-sent events for streamed responses

How It Works

Backend (TypeScript)          Frontend (TypeScript)
──────────────────            ──────────────────
1. Define procedures   ──▶    4. Import types
2. Define inputs              5. Call with autocomplete
3. Return data                6. Full type safety

No schemas. No codegen. Just TypeScript.

Example: Next.js App

1. Define Router (server)

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

const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;

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

export const appRouter = router({
  // Query (GET equivalent)
  getUser: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      const user = await db.user.findUnique({ where: { id: input.id } });
      return user;
    }),

  // Mutation (POST/PUT/DELETE equivalent)
  createPost: publicProcedure
    .input(z.object({
      title: z.string().min(1).max(100),
      content: z.string().min(10),
      published: z.boolean().default(false),
    }))
    .mutation(async ({ input }) => {
      const post = await db.post.create({ data: input });
      return post;
    }),

  // List with pagination
  listPosts: publicProcedure
    .input(z.object({
      limit: z.number().min(1).max(100).default(10),
      cursor: z.string().nullish(),
    }))
    .query(async ({ input }) => {
      const posts = await db.post.findMany({
        take: input.limit + 1,
        cursor: input.cursor ? { id: input.cursor } : undefined,
        orderBy: { createdAt: 'desc' },
      });

      let nextCursor: typeof input.cursor = undefined;
      if (posts.length > input.limit) {
        const nextItem = posts.pop();
        nextCursor = nextItem?.id;
      }

      return { posts, nextCursor };
    }),
});

// Export type for client
export type AppRouter = typeof appRouter;

2. Client Setup

// lib/trpc.ts
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/routers/_app';

export const trpc = createTRPCReact<AppRouter>();

// pages/_app.tsx
import { httpBatchLink } from '@trpc/client';
import { trpc } from '../lib/trpc';

function MyApp({ Component, pageProps }) {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: '/api/trpc',
        }),
      ],
    })
  );

  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        <Component {...pageProps} />
      </QueryClientProvider>
    </trpc.Provider>
  );
}

3. Use in Components (Full Type Safety!)

// components/UserProfile.tsx
import { trpc } from '../lib/trpc';

export function UserProfile({ userId }: { userId: string }) {
  // Fully typed query - autocomplete for 'getUser'
  const { data: user, isLoading } = trpc.getUser.useQuery({ id: userId });

  // Fully typed mutation
  const createPost = trpc.createPost.useMutation({
    onSuccess: () => {
      // Auto-refetch user data
      utils.getUser.invalidate({ id: userId });
    },
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>{user?.name}</h1>
      <button
        onClick={() => createPost.mutate({
          title: 'New Post',
          content: 'Content here',
          published: true,
        })}
      >
        Create Post
      </button>
    </div>
  );
}

Magic: If you rename a field in the backend, TypeScript immediately shows errors in every component using that field.

Key Features

Middleware

import { TRPCError } from '@trpc/server';

// Auth middleware
const authMiddleware = t.middleware(async ({ ctx, next }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({
    ctx: { ...ctx, user: ctx.user }, // Type narrowed to non-null
  });
});

// Protected procedure
const protectedProcedure = t.procedure.use(authMiddleware);

// Use in router
export const appRouter = router({
  getMyPosts: protectedProcedure.query(({ ctx }) => {
    return db.post.findMany({ where: { userId: ctx.user.id } });
  }),
});

Subscriptions (WebSocket)

// Server
import { observable } from '@trpc/server/observable';
import { EventEmitter } from 'events';

const ee = new EventEmitter();

export const appRouter = router({
  onNewMessage: publicProcedure.subscription(() => {
    return observable<{ text: string }>((emit) => {
      const handler = (data: { text: string }) => emit.next(data);
      ee.on('message', handler);
      return () => ee.off('message', handler);
    });
  }),
});

// Client
trpc.onNewMessage.useSubscription(undefined, {
  onData: (message) => {
    console.log('New message:', message.text);
  },
});

Batching

// Multiple queries in one HTTP request
httpBatchLink({
  url: '/api/trpc',
  maxURLLength: 2083, // Auto-batch when possible
});

// These three queries make 1 HTTP request instead of 3
const user = trpc.user.getById.useQuery({ id: '1' });
const posts = trpc.post.list.useQuery({ userId: '1' });
const stats = trpc.stats.getUser.useQuery({ id: '1' });

tRPC vs Alternatives

Framework Integrations

// Next.js
import { createNextApiHandler } from '@trpc/server/adapters/next';
export default createNextApiHandler({ router: appRouter });

// Express
import { createExpressMiddleware } from '@trpc/server/adapters/express';
app.use('/trpc', createExpressMiddleware({ router: appRouter }));

// Fastify
import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify';
server.register(fastifyTRPCPlugin, { prefix: '/trpc', trpcOptions: { router } });

// Cloudflare Workers
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
export default {
  fetch(request: Request) {
    return fetchRequestHandler({ endpoint: '/trpc', req: request, router: appRouter });
  },
};

常见问题

Q: tRPC 和 GraphQL 怎么选？ A: 如果你用纯 TypeScript 且前后端在同一个 monorepo，tRPC 更简单更快。如果你需要多语言客户端、复杂查询灵活性或已有 GraphQL 生态，选 GraphQL。tRPC 适合 80% 的内部应用，GraphQL 适合公共 API。

Q: 类型共享怎么实现的？ A: tRPC 使用 TypeScript 类型推断。你在 server 定义 router，export AppRouter 类型，client 导入这个类型。编译时 TypeScript 就知道所有 procedure 的输入输出类型——无需运行时开销或代码生成。

Q: 适合移动端吗？ A: 可以用于 React Native。tRPC 也支持 vanilla TypeScript 客户端，可以在任何 TypeScript 环境使用。不支持非 TypeScript 客户端（Python/Go/Java）——如果需要，GraphQL 或 REST 更合适。

来源与致谢

• GitHub: trpc/trpc — 40K+ ⭐ | MIT
• 官网: trpc.io