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](#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: | | Runtime | Type generation | |---|---|---| | Driven by | Nest DI container at boot | Rust CLI doing static analysis of your source | | Needs | classes listed in `providers` | decorators it can read literally | | Fails as | 404 / "no procedures" / undefined injection | stale or missing `AppRouter` | 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 ```shell 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 ```typescript // 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](references/module-config.md). ### 3. Write a router ```typescript // 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 ```shell 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: ```json { "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: | Decorator | tRPC equivalent | |---|---| | `@Query()` | `publicProcedure.query()` | | `@Mutation()` | `publicProcedure.mutation()` | | `@Subscription()` | `publicProcedure.subscription()` | `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: | Decorator | Yields | |---|---| | `@Input(key?)` | `opts.input`, or `opts.input[key]` | | `@Ctx()` | `opts.ctx` | | `@Options()` | the whole `opts` (typed as `ProcedureOptions`) | | `@RawInput()` | `opts.rawInput` (pre-validation) | | `@Type()` | `'query' \| 'mutation' \| 'subscription'` | | `@Path()` | the procedure path string | 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](references/routers.md). ## Middlewares and context Middlewares are `@Injectable()` classes implementing `TRPCMiddleware`, applied with `@UseMiddlewares(...)` on a class (all procedures) or a method (that one only), or globally via `globalMiddlewares`. Execution order is global → router → procedure → handler. ```typescript @Injectable() export class ProtectedMiddleware implements TRPCMiddleware { constructor(@Inject(UserService) private readonly userService: UserService) {} async use(opts: MiddlewareOptions<object>): Promise<MiddlewareResponse> { const result = await opts.next({ ctx: { user: await this.userService.current() } }); return result; } } ``` Two rules that cause most middleware bugs: always `return` the result of `next()` so the chain isn't swallowed, and pass added context *through* `next({ ctx })` rather than mutating `opts.ctx` in place. Context is a class implementing `TRPCContext` with a `create(opts)` method, registered in `providers` and passed to `forRoot({ context })`. It runs once per request and is the right home for the request object, session, and per-request loaders. Full treatment including typing context across a middleware chain and procedure `meta`: [references/middlewares-and-context.md](references/middlewares-and-context.md). ## Recommended file layout Mirrors NestJS conventions, which is the whole point of the adapter: ``` src ├── app.module.ts ├── app.context.ts ├── main.ts ├── @generated/ # CLI output — gitignore or commit, but be consistent └── user/ ├── user.router.ts # the "controller" — thin, no business logic ├── user.service.ts # business logic, unit-testable without tRPC ├── user.schema.ts # Zod schemas + inferred types, shared by both └── protected.middleware.ts ``` Keep routers thin. A router method that only validates, delegates to a service, and maps errors stays testable and keeps the CLI's job easy. ## Docs errata The official docs mix v1 and v2 content. These are the ones that will actually break your build: - **`@Ctx()`, not `@Context()`.** The routers and middlewares pages show `@Context()`; the exported decorator is `Ctx`. (`Context` as an identifier does exist in the docs' prose as a *type* name, which is where the confusion comes from.) - **`MiddlewareOptions`, not `TRPCMiddlewareOptions`.** The latter is not exported. - **`TRPCMiddleware<TMeta>` — the single generic is the meta type, not the context type.** The docs' `implements TRPCMiddleware<Context>` is wrong. Context types are supplied via `MiddlewareOptions<TContext, TReturnContext, TMeta>` on the `use()` signature. - **`autoSchemaFile` and `schemaFileImports` are v1 options.** They are absent from the v2 `TRPCModuleOptions` type and will be TypeScript errors, even though the context, client, and integrations pages still show `autoSchemaFile`. Control output with the CLI's `--output` flag instead. - **`nestjs-trpc/types` is a v1 import path.** v1's ts-morph generator wrote helper types (`Context`, `{Middleware}Context`) into the package; v2's Rust CLI emits a single `server.ts` instead. Don't import from `nestjs-trpc/types` on v2 — declare your context types yourself. - **`@Middlewares()` is deprecated** in favour of `@UseMiddlewares()`, to match `@UseGuards`. - The middlewares page's first example has a literal typo (`constructror`) and a missing `async`. Don't copy it verbatim. ## Reference files Read these when the task goes past the basics: - **[references/routers.md](references/routers.md)** — procedure and parameter decorators in full, subscriptions/SSE with `AbortSignal` cleanup, alias merging, error handling, testing routers. - **[references/middlewares-and-context.md](references/middlewares-and-context.md)** — `MiddlewareOptions` generics, context propagation and typing, `meta`-driven authorization, global middleware ordering. - **[references/module-config.md](references/module-config.md)** — every `forRoot` option, SSE and JSONL keep-alive settings, `onError` handlers, custom loggers, transformers. - **[references/codegen-and-client.md](references/codegen-and-client.md)** — CLI flags, ESM `--import-extension`, schema-flattening failures, consuming `AppRouter` from React / Next.js / vanilla clients, `AppRouterHost` for e2e tests and trpc-ui. - **[references/api-reference.md](references/api-reference.md)** — exact exported symbols and type signatures transcribed from the shipped `.d.ts`. Check here before guessing a name.