NestJS tRPC

You can attach arbitrary metadata to procedures using the meta property in @Query() or @Mutation() decorators. Middlewares can then read this metadata to implement logic like role-based access control (RBAC).

To achieve full type safety, pass the metadata interface as a generic to the TRPCMiddleware implementation and use it within MiddlewareOptions.

// 1. Define metadata in the procedure
@Query({
  input: z.object({ userId: z.string() }),
  meta: { roles: ['admin'] },
})
async getUser(@Input('userId') userId: string) {}

// 2. Read metadata in the middleware
interface RolesMeta { roles: string[]; }

@Injectable()
export class RolesMiddleware implements TRPCMiddleware<RolesMeta> {
  async use(opts: MiddlewareOptions<AuthMiddlewareContext, Record<string, unknown>, RolesMeta>): Promise<MiddlewareResponse> {
    const { meta, ctx, next } = opts;

    if (!meta.roles.includes(ctx.auth.userId)) {
      throw new TRPCError({ message: 'Insufficient permissions.', code: 'FORBIDDEN' });
    }

    return next();
  }
}

Middlewares can augment the context passed to downstream procedures by calling next({ ctx: { ... } }).

To ensure type safety, use the TReturnContext generic in MiddlewareOptions. When a middleware modifies the context, nestjs-trpc generates a new type named [MiddlewareName]MiddlewareContext (e.g., AuthMiddlewareContext). You can then import this generated type and use it with the @Context() decorator in your procedures.

// 1. Define the return context shape
interface AuthReturnContext {
  auth: { userId: string };
}

// 2. Implement middleware with the generic
@Injectable()
export class AuthMiddleware implements TRPCMiddleware {
  async use(opts: MiddlewareOptions<Context, AuthReturnContext>): Promise<MiddlewareResponse> {
      const { ctx, next } = opts;
      // ... logic to get session ...
      return next({
        ctx: { auth: { userId: session.user.id } }
      });
  }
}

// 3. Use the generated type in a procedure
@UseMiddlewares(AuthMiddleware)
@Query({ output: userSchema })
async getUserProfile(@Context() ctx: AuthMiddlewareContext): Promise<User> {
  const { userId } = ctx.auth; // Fully typed
  return await this.userService.getUserById(userId);
}

When deciding whether to migrate from GraphQL to NestJS-tRPC, consider the following advantages and trade-offs:

Advantages of NestJS-tRPC

• End-to-End Type Safety: Achieves seamless type inference from backend to frontend without requiring code generation, reducing runtime errors.
• Simplified Development: Eliminates the need for manual schema definitions and resolvers. You can use existing models and business logic directly, reducing boilerplate.
• Familiar NestJS Patterns: Integrates smoothly with the NestJS ecosystem, allowing you to use existing NestJS knowledge.
• Performance: Offers a lighter-weight solution with reduced overhead in request processing and response serialization compared to full GraphQL implementations.
• Flexible Querying: Supports query composition, including batching multiple procedure calls in a single HTTP request and efficient caching/invalidation strategies.
• Developer Experience: Provides full IDE support (autocomplete, IntelliSense), easier debugging, and simplified testing.
• Gradual Migration: Can be integrated alongside existing NestJS modules, allowing for a phased transition.

Migration Considerations

• Learning Curve: Teams must learn tRPC concepts (though these are generally straightforward for TypeScript developers).
• Client-Side Updates: You must update existing client-side code to use the tRPC client instead of GraphQL queries.
• Feature Parity: Evaluate if tRPC meets all your current use cases.

WARNING

If your application relies heavily on GraphQL-specific features like subscriptions, carefully assess if tRPC can meet these needs before migrating.

The AppRouter acts as a bridge between NestJS's runtime-centric architecture and tRPC's compile-time centric type inference.

1. Definition: You define your API using @Router() classes and decorators like @Query(), @Mutation(), and @Input(). You can use the alias option in @Router({ alias: '...' }) to name the router segment in the tRPC tree.
2. Generation: When autoSchemaFile is configured, the library generates a file (e.g., src/@generated/server.ts) that contains a t.router({...}) definition.
3. Type Inference: This generated file exports export type AppRouter = typeof appRouter;. Your frontend client imports this type to provide autocomplete and type checking.
4. Runtime: The generated code contains no actual logic; it uses placeholders to satisfy TypeScript. Your real logic is executed by the NestJS application at runtime.

// 1. Define Router in NestJS
@Router({ alias: 'users' })
export class UserRouter {
    @Query({ input: z.object({ userId: z.string() }) })
    async getUserById(@Input('userId') userId: string) {
        // Real logic here
    }
}

// 2. Generated Output (src/@generated/server.ts)
const appRouter = t.router({
    users: {
        getUserById: publicProcedure
            .input(z.object({ userId: z.string() }))
            .query(async () => 'PLACEHOLDER_DO_NOT_REMOVE' as any),
    },
});
export type AppRouter = typeof appRouter;

You can apply middlewares at three levels of granularity. The execution order is: Global Middlewares $\rightarrow$ Router Middlewares $\rightarrow$ Procedure Middlewares $\rightarrow$ Handler.

1. Global Middlewares: Apply to every procedure in the application by adding them to the globalMiddlewares array in TRPCModule.forRoot().
2. Router Middlewares: Apply to all procedures within a specific router class using the @UseMiddlewares() decorator on the class.
3. Procedure Middlewares: Apply to a specific method (query or mutation) using the @UseMiddlewares() decorator on the method.

// Global Middleware Registration
@Module({
  imports: [
    TRPCModule.forRoot({
      globalMiddlewares: [LoggedMiddleware, ErrorReportingMiddleware],
    }),
  ],
  providers: [LoggedMiddleware, ErrorReportingMiddleware],
})
export class AppModule {}

// Router and Procedure Middleware Application
@Router()
export class DogsRouter {
  @UseMiddlewares(LoggedMiddleware, AuthMiddleware)
  @Query({ output: z.array(dogSchema) })
  async findAll(): Promise<Dog[]> {
    // ...
  }
}