Installation

This document will guide you through the installation and setting up of NestJS tRPC in your nestjs project.

NestJS tRPC supports NestJS 9 through 12 on both the Express and Fastify adapters, and requires tRPC v11 with Zod 3 or Zod 4.

⚠️

If you don't have a NestJS project setup yet, please visit our NestJS Quickstart Guide or check out the official NestJS documentation.

Manual Installation

To install NestJS tRPC with your preferred package manager, you can use any of the following commands:

npm install nestjs-trpc

Initialization

Once the packages are installed, we can import the TRPCModule and configure it with the forRoot() static method.

app.module.ts

import { Module } from '@nestjs/common';
import { TRPCModule } from 'nestjs-trpc';
 
@Module({
  imports: [
    TRPCModule.forRoot({
      // Optional: specify custom base path (default: '/trpc')
      // basePath: '/api/trpc',
    }),
  ],
})
export class AppModule {}

The forRoot() method takes an options object as an argument. These options are passed through to the underlying express or fastify driver.

Generate Types

Run the CLI to generate your AppRouter types:

npx nestjs-trpc generate

This scans your routers and creates a TypeScript file with your complete router types. For watch mode during development:

npx nestjs-trpc watch

By default, types are generated to ./src/@generated/server.ts. You can customize this with the --output flag:

npx nestjs-trpc generate --output ./src/trpc/types.ts

For projects using "moduleResolution": "NodeNext" or "Node16" in tsconfig.json, .js extensions are added automatically. The CLI searches the nearest tsconfig.json walking up from your source directory, so it works correctly whether you run from the project root or a subdirectory. Override with --import-extension js|none|auto:

npx nestjs-trpc generate --import-extension none

Note: If your project uses moduleResolution: bundler (e.g. with Vite or esbuild) but runs on plain Node ESM at runtime, auto will report false because bundler mode does not require explicit file extensions at compile time. Use --import-extension=js explicitly in that case.

Start your NestJS server. You should be good to go! 🎉

Module Options

You can import TRPCModuleOptions type from nestjs-trpc to safely assert all of the TRPCModule option types.

import { TRPCModule, TRPCModuleOptions } from 'nestjs-trpc';
const trpcOptions: TRPCModuleOptions = {
  basePath: '/trpc',
};

Prop	Type	Default
`basePath`	`string`	`"/trpc"`
`context`	`TRPCContext`	-
`trpc`	`TRPCOptions`	-
`logger`	`LoggerService`	`ConsoleLogger`
`onError`	`TRPCErrorHandler`	-
`globalMiddlewares`	`Array<TRPCMiddleware>`	`[]`

Native tRPC Options

NestJS-shaped options (DI classes, autoSchemaFile, basePath) sit at the top level of forRoot(). Anything you would pass to tRPC itself goes in the trpc key, spelled exactly as tRPC spells it:

app.module.ts

import { Module } from '@nestjs/common';
import { TRPCModule } from 'nestjs-trpc';
import superjson from 'superjson';
 
@Module({
  imports: [
    TRPCModule.forRoot({
      basePath: '/trpc',
      context: AppContext,
      trpc: {
        transformer: superjson,
        allowMethodOverride: true,
        responseMeta: (opts) => ({ headers: { 'cache-control': 'no-store' } }),
      },
    }),
  ],
})
export class AppModule {}

The module routes root config options (transformer, errorFormatter, sse, jsonl, ...) to initTRPC.create() and everything else to the active Express or Fastify adapter. The module-owned router, createContext, and onError options cannot be set through trpc — use the context and onError DI classes instead.

The top-level transformer, errorFormatter, sse, and jsonl options are deprecated in favor of the trpc key and will be removed in the next major version.

Custom Logger

By default, NestJS tRPC uses the built-in NestJS ConsoleLogger. You can provide your own logger by passing any implementation of the NestJS LoggerService interface:

app.module.ts

import { Module } from '@nestjs/common';
import { TRPCModule } from 'nestjs-trpc';
import { MyLogger } from './my-logger.service';
 
@Module({
  imports: [
    TRPCModule.forRoot({
      logger: new MyLogger(),
    }),
  ],
})
export class AppModule {}

This is useful when replacing the default NestJS logger with a production-grade alternative such as Pino (opens in a new tab), Winston (opens in a new tab), or any other logger that implements the LoggerService interface.

Supported Platforms

The CLI binary is available for:

macOS (Intel and Apple Silicon)
Linux (x64 and ARM64)
Windows (x64)

NestJS Quickstart