GRPC transport layer for the NestJS framework


2.2.04 years ago5 years agoMinified + gzip package size for @fresh8/nestjs-grpc-transport in KB



CircleCI Coverage Status styled with prettier

GRPC transport layer for the NestJS framework.


  • Typescript 2.x
  • Node boron
  • Npm 5.x
  • NestJS v3.0.1 (there is breaking change in v3.1.1).


npm install @fresh8/nestjs-grpc-transport --save


Create your protobuf definition sample.proto:

syntax = "proto3";

package sample;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}

message HelloRequest {
  string name = 1;

message HelloReply {
  string message = 1;

Generate your Typescript interfaces using rxjs-grpc.

./node_modules/.bin/rxjs-grpc -o grpc-namespaces.ts *.proto

Create your first controller. The @rpc decorator provides some metadata needed by Nest, and takes care of providing an Observable for rxjs-grpc.

import { Controller } from '@nestjs/common'
import { rpc } from '@fresh8/nestjs-grpc-transport'

import { sample } from './grpc-namespaces'

export default class TestController {
   * sayHello RPC method
  async sayHello(request: sample.HelloRequest): Promise<sample.HelloReply> {
    const res = await this.someAsyncThing()
    return { message: `Hello ${request.name}: ${res}` }
   * Some dummy async method. This might be a call to a database in
   * a proper application.
  someAsyncThing() {
    return Promise.resolve(`:)`)

Create your GRPC server and provide it to your NestJS application.

import { Module } from '@nestjs/common'
import { NestFactory } from '@nestjs/core'
import { createServer } from '@fresh8/nestjs-grpc-transport'

import { sample } from './grpc-namespaces'
import { TestController } from './test-controller'

 * Example application
  controllers: [TestController]
export class ApplicationModule {}

 * Create a nest application that runs over GRPC.
const app = NestFactory.createMicroservice(ApplicationModule, {
  strategy: createServer<sample.ServerBuilder>({
    host: '',
    port: 50051,
    protoPath: `path/to/sample.proto`,
    packageName: 'sample',
    serviceName: 'Greeter'

 * Start your app as normal.
app.listen(() => {
  console.log('GRPC server running on')


A simple example project is provided here.

A note on Exceptions handling

Nestjs itself catches and handles exceptions as part of its Exception Filters feature. nestjs-grpc-transport only transforms it to the format expected by rxjs-grpc.

To the best of our understanding this implies:

  • Any exception that is not an instance of @nestjs/microservices/RpcException will be reported as Internal error (code 13).
  • To send errors other than Internal simply throw a new RpcException with the following property:
    • code : number: The exception code. Defaults to 13.
    • message : string: An additional message. Defaults to "Internal Server Error"
  • Exceptions are not logged.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.