nest-trpc-native

Setup Patterns

For explicit monorepo and microservice transport topologies, see website/docs/advanced/monorepo.md and website/docs/advanced/microservices.md.

For explicit forRootAsync + ConfigService + middleware, run:

• npm run test --workspace nest-trpc-native-sample-09-config-middleware

Requirements

• Node.js >=20
• NestJS 11.x
• tRPC 11.x

For the supported surface and compatibility policy, see website/docs/support-policy.md.

Installation

npm i nest-trpc-native @trpc/server

Required peers:

npm i @nestjs/common @nestjs/core reflect-metadata rxjs

Optional (recommended for schema inference and tRPC-style validation, Zod v4):

npm i zod@^4

Zero Runtime Dependencies

nest-trpc-native is intentionally a bridge package with an empty runtime dependency block ("dependencies": {}).

Why:

• It should not pull a second NestJS runtime into the app.
• The host app controls Nest/tRPC versions through peer dependencies.
• The integration relies on capabilities already present in Nest apps and Node:
  • reflection (reflect-metadata)
  • DI/discovery (@nestjs/common, @nestjs/core)
  • tRPC runtime/adapters (@trpc/server)
  • file/path generation via Node built-ins (fs, path)

Is Zod Required?

No. Zod is optional.

• If you use Nest-style validation (class-validator + ValidationPipe), you can use nest-trpc-native without Zod schemas.
• If you use tRPC-style schema definitions (@Query({ input: z.object(...) }), @Mutation({ output: ... })) and schema generation based on those schemas, then your app should install Zod v4.

We support Zod v4 as an optional peer dependency so non-Zod users are not forced to install it.

Nest Compatibility Boundary

Enhancer lifecycle behavior is preserved through a narrow internal boundary so Nest-version-sensitive wiring stays isolated. See website/docs/advanced/nest-internals.md.

Quick Start

Non-Zod (class-validator + ValidationPipe)

import { Module, UsePipes, ValidationPipe } from '@nestjs/common';
import { IsString, MinLength } from 'class-validator';
import { Input, Mutation, Query, Router, TrpcModule } from 'nest-trpc-native';

class CreateUserDto {
  @IsString()
  @MinLength(1)
  name!: string;
}

@Router('users')
class UsersRouter {
  @Query()
  list() {
    return [{ id: '1', name: 'Ada' }];
  }

  @Mutation()
  @UsePipes(new ValidationPipe({ whitelist: true }))
  create(@Input() input: CreateUserDto) {
    return { id: '2', ...input };
  }
}

@Module({
  imports: [
    TrpcModule.forRoot({
      path: '/trpc',
      autoSchemaFile: 'src/@generated/server.ts',
    }),
  ],
  providers: [UsersRouter],
})
export class AppModule {}

Zod

import { Module } from '@nestjs/common';
import {
  Input,
  Mutation,
  Query,
  Router,
  TrpcContext,
  TrpcModule,
} from 'nest-trpc-native';
import { z } from 'zod';

const CreateUserSchema = z.object({ name: z.string().min(1) });

@Router('users')
class UsersRouter {
  @Query({ output: z.array(z.object({ id: z.string(), name: z.string() })) })
  list(@TrpcContext('requestId') requestId: string) {
    return [{ id: requestId, name: 'Ada' }];
  }

  @Mutation({ input: CreateUserSchema })
  create(@Input() input: { name: string }) {
    return { id: '1', ...input };
  }
}

@Module({
  imports: [
    TrpcModule.forRoot({
      path: '/trpc',
      autoSchemaFile: 'src/@generated/server.ts',
    }),
  ],
  providers: [UsersRouter],
})
export class AppModule {}

Typed Context

Both TrpcModule.forRoot() and TrpcModule.forRootAsync() accept an optional generic that types the createContext return value. This gives you compile-time safety and autocompletion on your context factory without changing any runtime behavior.

interface MyContext {
  requestId: string;
  userId?: number;
}

// Static configuration
TrpcModule.forRoot<MyContext>({
  createContext: ({ req }) => ({
    requestId: req.headers['x-request-id'] ?? crypto.randomUUID(),
    userId: extractUserId(req),
  }),
});

// Async configuration
TrpcModule.forRootAsync<MyContext>({
  useFactory: (config: ConfigService) => ({
    createContext: ({ req }) => ({
      requestId: req.headers['x-request-id'] ?? crypto.randomUUID(),
      // TypeScript error if you forget `userId` or add unknown fields
    }),
  }),
  inject: [ConfigService],
});

The generic defaults to any, so existing code without the type parameter continues to work unchanged.

Workspace Commands

npm install
npm run build
npm run test
npm run ci:sample

ci:showcase remains as a compatibility alias.

Sample Commands

npm run start --workspace nest-trpc-native-showcase
npm run start:fastify --workspace nest-trpc-native-showcase
npm run client --workspace nest-trpc-native-showcase
npm run sample:focused

For sample details, open sample/README.md and sample/00-showcase/README.md.