Build Type-Safe Full-Stack APIs with tRPC

Builds fully type-safe TypeScript APIs with tRPC, with types flowing directly from the server router to the client so every API call is autocompleted, validated at compile time, and safe to refactor - no schema or code-generation step. Core concepts: a router groups related procedures (query for reads, mutation for writes, subscription for real-time streams); every procedure's input is validated with a Zod schema, so the handler receives already-typed, already-validated input with no manual parsing; context is shared per-request state (auth session, database client, headers) built once by a context factory - Next.js App Router and Pages Router need separate factories, since App Router handlers receive a fetch Request rather than a Node.js NextApiRequest; and middleware chains run before a procedure to handle auth, logging, or request enrichment, and can extend the context for downstream procedures. The setup flow: install the tRPC/React Query/Zod packages; create the tRPC instance with initTRPC.context<Context>().create() and export router/publicProcedure/middleware; define an auth middleware that throws TRPCError({ code: 'UNAUTHORIZED' }) when there's no session and export a protectedProcedure built from it; define routers per domain (for example a post router with list/byId/create/delete procedures, each declaring its own Zod input schema); compose them into one appRouter in root.ts, exporting only the AppRouter type, never the router value, for the client; mount the API handler with fetchRequestHandler and the fetch-based context factory for App Router; and set up the client with createTRPCReact<AppRouter>() plus a React Query provider using httpBatchLink.

Use it when building a TypeScript full-stack app (Next.js, Remix, Express plus React) where client and server share one repo, when end-to-end type safety on API calls is wanted without REST/GraphQL schema overhead, when adding real-time subscriptions to an existing tRPC setup, when designing multi-step middleware (auth, rate limiting, tenant scoping) on procedures, or when incrementally migrating an existing REST/GraphQL API to tRPC. Hard rules: export only the AppRouter type from server code, never import the appRouter value on the client; use separate context factories - one for the HTTP handler, one for Server Components and direct server-side callers - rather than casting an empty object with as any; validate every input with Zod rather than trusting raw input; split routers by domain and merge them in root.ts; extend context in middleware instead of re-querying the database per procedure; and always enforce authorization inside protectedProcedure itself, never relying on client-side checks alone. Rate-limit public procedures via middleware, and keep error messages public-safe with TRPCError rather than leaking internal details or stack traces to the client.

Install:

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

A typed, validated procedure:

create: protectedProcedure
    .input(
      z.object({
        title: z.string().min(1).max(200),
        body: z.string().min(1),
      })
    )
    .mutation(async ({ ctx, input }) => {
      return ctx.db.post.create({
        data: { ...input, authorId: ctx.session.user.id },
      });
    }),

On the client, the same procedure is called as trpc.post.create.useMutation({ onSuccess: () => utils.post.list.invalidate() }), and a query as trpc.post.list.useQuery({ limit: 10 }) - both fully typed from the server router with no separate schema. Subscriptions use protectedProcedure.subscription() returning an observable, consumed on the client via useSubscription, routed through a wsLink split from the httpBatchLink used for queries and mutations.

Built on @trpc/server, @trpc/client, @trpc/react-query, and @tanstack/react-query, with Zod for input validation; works with Next.js App Router (@trpc/server/adapters/fetch and fetchRequestHandler) or Pages Router (a separate nextjs adapter), and with an auth provider like Next-Auth for session context. Common integration failures it flags: using the Pages Router nextjs adapter under App Router instead of the fetch adapter, importing AppRouter as a value instead of a type import, and forgetting splitLink so subscriptions never reach wsLink.

Developers building a TypeScript full-stack app who want compile-time-checked API calls between client and server without maintaining a separate REST/GraphQL schema, and who need correct context and middleware patterns for auth, Server Components, and real-time subscriptions.