Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GrpcModule
✓ import { GrpcModule } from 'nestjs-grpc'
✗ const GrpcModule = require('nestjs-grpc').GrpcModule
ESM import works in Node >=18. CommonJS require also works but use destructuring.
GrpcController
✓ import { GrpcController } from 'nestjs-grpc'
✗ import { GrpcController } from '@nestjs/common'
@GrpcController is specific to this package, not part of @nestjs/common.
GrpcMethod
✓ import { GrpcMethod } from 'nestjs-grpc'
✗ import { GrpcMethod } from '@nestjs/microservices'
Do not confuse with @nestjs/microservices' GrpcMethod; this package provides its own enhanced version.
GrpcLogLevel
✓ import { GrpcLogLevel } from 'nestjs-grpc'
Enum used for configuring log levels in GrpcModule.forProvider.
GrpcException
✓ import { GrpcException } from 'nestjs-grpc'
Base exception class for gRPC errors; extends RpcException.
Setup a NestJS gRPC server: import GrpcModule with proto config, create a controller with @GrpcController and @GrpcMethod, and use generated types from CLI.
// Install: npm install nestjs-grpc
// Generate types from proto files: npx nestjs-grpc generate --proto "./protos/**/*.proto" --output "./src/generated"
// app.module.ts
import { Module } from '@nestjs/common';
import { GrpcModule, GrpcLogLevel } from 'nestjs-grpc';
import { AuthController } from './auth.controller';
import { AuthService } from './auth.service';
@Module({
imports: [
GrpcModule.forProvider({
protoPath: './protos/auth.proto',
package: 'auth',
url: '0.0.0.0:50051',
logging: {
enabled: true,
level: GrpcLogLevel.DEBUG,
context: 'GrpcModule',
},
}),
],
controllers: [AuthController],
providers: [AuthService],
})
export class AppModule {}
// auth.controller.ts
import { Injectable } from '@nestjs/common';
import { Observable } from 'rxjs';
import { GrpcController, GrpcMethod, GrpcStream, GrpcException } from 'nestjs-grpc';
import { ValidateTokenRequest, ValidateTokenResponse, LoginRequest, LoginResponse, StreamUsersRequest, User } from './generated/auth';
@GrpcController('AuthService')
export class AuthController {
constructor(private readonly authService: AuthService) {}
@GrpcMethod('ValidateToken')
async validateToken(request: ValidateTokenRequest): Promise<ValidateTokenResponse> {
const user = await this.authService.findByToken(request.token);
if (!user) {
throw new GrpcException('Invalid token', 16); // UNAUTHENTICATED
}
return { valid: true, user };
}
@GrpcMethod('Login')
async login(request: LoginRequest): Promise<LoginResponse> {
const user = await this.authService.validateCredentials(request.email, request.password);
if (!user) {
throw new GrpcException('Invalid credentials', 7); // PERMISSION_DENIED
}
const token = await this.authService.generateToken(user);
return { token, user };
}
@GrpcStream('StreamUsers')
streamUsers(request: StreamUsersRequest): Observable<User> {
return this.authService.getUsersStream(request.limit);
}
}
Errors
Common errors & fixes
Error: Method not found
The gRPC method name in @GrpcMethod doesn't match the proto definition's RPC method name.
fixCheck that the string passed to @GrpcMethod ('ValidateToken') exactly matches the RPC name in the proto file (rpc ValidateToken). Error: 12 UNIMPLEMENTED: Method not implemented
The controller does not have a handler for a method defined in the proto service, or the handler method's name is incorrect.
fixEnsure every RPC method in the proto has a corresponding @GrpcMethod or @GrpcStream handler in the controller class.
Error: ENOENT: no such file or directory, open './protos/auth.proto'
The protoPath in GrpcModule.forProvider points to a non-existent file or the path is resolved incorrectly.
fixUse an absolute path or ensure the working directory is set correctly. Example: protoPath: resolve(__dirname, '../protos/auth.proto').
TypeError: Cannot read properties of undefined (reading 'name')
The @GrpcController decorator is missing the service name argument, or the decorator is applied to a non-class (e.g., a function).
fixApply @GrpcController('ServiceName') to a class and ensure the service name string matches the proto service name. Audit
Dependencies
@nestjs/commonrequiredPeer dependency for NestJS modules and decorators
@nestjs/corerequiredPeer dependency for NestJS core functionality
@nestjs/microservicesrequiredPeer dependency for gRPC transport layer
reflect-metadatarequiredPeer dependency required for decorators and DI
rxjsrequiredPeer dependency for reactive streams and Observable support