@relab/nestjs-grpc

Purpose

Helpers for integrating gRPC with NestJS microservices. Provides a one-call setup to attach a gRPC microservice and a global exception filter that maps NestJS errors to proper gRPC status codes.

Key Features

• One-call setup: Attach a gRPC microservice transport to your NestJS app.
• Global gRPC exception filter: Converts HttpException, RpcException, and generic Error to gRPC-compatible errors with appropriate status codes.
• Config inheritance: Microservice inherits your main app configuration.

Installation

pnpm add @relab/nestjs-grpc

Usage

Attach gRPC microservice

main.ts

import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'
import { configureGrpcMicroservice } from '@relab/nestjs-grpc'

async function bootstrap() {
    const app = await NestFactory.create(AppModule)

    await configureGrpcMicroservice(app, {
        package: ['your.protobuf.package'],
        protoPath: ['path/to/your.proto'],
        url: '0.0.0.0:50051',
    })

    await app.startAllMicroservices()
    await app.listen(3000)
}

bootstrap()

API

configureGrpcMicroservice(app, options)

Attaches a gRPC microservice to your NestJS app and registers a global GrpcExceptionFilter.

Parameters

• app: INestApplication — Your NestJS application instance.
• options: GrpcOptions['options'] — Standard NestJS gRPC transport options, e.g. package, protoPath, url, etc.

Behavior

• Registers GrpcExceptionFilter globally for RPC contexts.
• Maps errors to gRPC status codes:
  • HttpException → mapped to INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED, NOT_FOUND, ALREADY_EXISTS, INTERNAL, UNAVAILABLE (based on HTTP status).
  • RpcException → passes through original error payload.
  • Error/unknown → INTERNAL with name and details.
• Connects the microservice with inheritAppConfig: true so global pipes/filters/interceptors are reused.

Import

export { configureGrpcMicroservice } from '@relab/nestjs-grpc'

License

MIT