Nestjs Trpc

NestJS-tRPC

nestjs-trpc lets you define tRPC procedures as decorated NestJS classes instead of chaining t.procedure builders. Routers are DI-aware classes that look like controllers; a separate CLI reads those decorators and emits an AppRouter type for the client.

Verified against v2.13.0. The published docs at nestjs-trpc.io still contain v1-era examples in several places. Where this skill and the docs disagree, this skill matches the shipped .d.ts files and the official examples/ in the repo — see Docs errata for the specific traps.

The one thing to internalize

There are two separate systems that both need to be correct, and they fail independently:

A router that works at runtime but was never picked up by the CLI produces a client with no types, and vice versa. When something is wrong, first ask which of the two is broken.

Setup workflow

1. Install

npm install nestjs-trpc zod @trpc/server

Peer deps (v2.13.0): @nestjs/common & @nestjs/core ^9.3.8 || ^10 || ^11, @trpc/server ^11, zod ^3.14 || ^4, rxjs 7.8.1, reflect-metadata ^0.1.13 || ^0.2. tRPC v11 is required — v10 will not work.

Standard NestJS tsconfig.json requirements apply: experimentalDecorators: true, emitDecoratorMetadata: true. tsc must be resolvable, because the CLI shells out to it to typecheck what it generates.

2. Register the module

// app.module.ts
import { Module } from '@nestjs/common';
import { TRPCModule } from 'nestjs-trpc';
import { UserRouter } from './user.router';
import { UserService } from './user.service';
import { ProtectedMiddleware } from './protected.middleware';
import { AppContext } from './app.context';

@Module({
  imports: [
    TRPCModule.forRoot({
      context: AppContext,
    }),
  ],
  providers: [UserRouter, AppContext, UserService, ProtectedMiddleware],
})
export class AppModule {}

Routers, middlewares, and the context class are all ordinary providers. Listing them in providers is what makes DI work — forgetting a router here is the single most common reason procedures silently don't exist at runtime.

Default mount point is /trpc; override with basePath. Full option table in references/module-config.md.

3. Write a router

// user.router.ts
import { Inject } from '@nestjs/common';
import { Router, Query, Mutation, UseMiddlewares, Input, Ctx } from 'nestjs-trpc';
import { TRPCError } from '@trpc/server';
import { z } from 'zod';
import { UserService } from './user.service';
import { ProtectedMiddleware } from './protected.middleware';
import { userSchema, type User } from './user.schema';

@Router({ alias: 'users' })
export class UserRouter {
  constructor(@Inject(UserService) private readonly userService: UserService) {}

  @Query({
    input: z.object({ userId: z.string() }),
    output: userSchema,
  })
  @UseMiddlewares(ProtectedMiddleware)
  async getUserById(@Input('userId') userId: string): Promise<User> {
    const user = await this.userService.getUser(userId);

    if (user == null) {
      throw new TRPCError({ message: 'Could not find user.', code: 'NOT_FOUND' });
    }

    return user;
  }
}

Client call site: trpc.users.getUserById.query({ userId }). The alias sets that first segment — without it the class name is used.

4. Generate the client type

npx nestjs-trpc generate      # one-shot
npx nestjs-trpc watch         # regenerate on change during development

Writes server.ts (containing export type AppRouter = typeof appRouter) to ./src/@generated by default; --output <dir> moves it. This is a build step, not a runtime import — the generated file is types only, and your procedures still execute through the Nest-managed router at runtime.

Add it to your scripts so it can't drift:

{
  "scripts": {
    "dev": "nestjs-trpc watch & nest start --watch",
    "build": "nestjs-trpc generate && nest build"
  }
}

Run nestjs-trpc generate --dry-run in CI to fail the build when the committed types are stale.

Writing procedures

Three procedure decorators, all taking { input?, output?, meta? }, all optional:

input validates and types the incoming payload. output is optional — omit it and the return type is inferred from the method signature (since v2.11.0). Prefer an explicit output on anything crossing a trust boundary, because it strips fields the client shouldn't see; a leaked password column is the classic version of this bug. Note the example schema above deliberately keeps password in userSchema only to mirror the upstream docs — in real code, define a separate public-facing schema.

Any Standard Schema validator works (Zod, Valibot, ArkType, Yup, Superstruct), but the CLI's schema flattening is built around Zod — stay on Zod unless you have a reason not to.

Parameter decorators pull pieces out of the tRPC opts object:

Throw TRPCError from @trpc/server for client-visible failures. Nest's HttpException is not translated into a tRPC error shape, so it surfaces as an opaque 500.

Details, subscription patterns, and router merging: references/routers.md.