Registry / devops / moleculer-grpc-api

moleculer-grpc-api

library1.2.5jsnpmunverified

Mixin for Moleculer API Gateway that adds gRPC server support. Current stable version: 1.2.5. Release cadence: irregular, based on community contributions. Differentiators: seamless integration with Moleculer microservice framework, allows gRPC clients to call Moleculer actions via alias mappings, supports authentication via Moleculer actions, and automatically loads .proto files from a directory. Has limited documentation and no official TypeScript types.

devops

npm install moleculer-grpc-api

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MOLECULER-GRPC-API

moleculer-grpc-api

devopsjavascriptv1.2.5

harness data pending

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.

GrpcService

✓ import { GrpcService } from 'moleculer-grpc-api'

✗ const GrpcService = require('moleculer-grpc-api')

CommonJS require is acceptable but named import is preferred for consistency; the package is CJS-only.

GrpcService (default)

✓ const { GrpcService } = require('moleculer-grpc-api')

✗ const MoleculerGrpcApi = require('moleculer-grpc-api').default

The package does not export a default; it only exports the named mixin function GrpcService.

GrpcService options

✓ GrpcService({ directory: './protos', port: 50051, aliases: {...} })

✗ new GrpcService() or GrpcService.create()

GrpcService is a factory function that returns a mixin object, not a constructor.

Creates a Moleculer broker with a greeter action and an API gateway mixin that sets up a gRPC server mapping the Greeter service's sayHello RPC to the greeter.sayHello action.

const { ServiceBroker } = require('moleculer'); const ApiGateway = require('moleculer-web'); const { GrpcService } = require('moleculer-grpc-api'); const broker = new ServiceBroker(); broker.createService({ name: 'greeter', actions: { sayHello: { params: { name: 'string' }, handler(ctx) { return `Hello ${ctx.params.name}`; } } } }); broker.createService({ name: 'api', mixins: [ApiGateway, GrpcService({ directory: __dirname + '/../protos', port: 50051, aliases: { 'helloworld.Greeter': { 'sayHello': 'greeter.sayHello' } } })] }); broker.start();

Debug

Known issues

gotchaThe 'directory' option expects an absolute path. Relative paths may fail if not resolved correctly.

fix

Use path.resolve(__dirname, 'protos') or __dirname + '/protos' to ensure absolute path.

affects: >=1.0.0

gotchaAlias format must match 'protoPackage.protoService' exactly, including uppercase letters. Mismatches cause silent failures.

fix

Double-check proto file package and service names. They are case-sensitive.

affects: >=1.0.0

deprecatedThe package uses the deprecated 'grpc' npm package instead of '@grpc/grpc-js'. It may break with newer Node versions.

fix

Consider switching to an alternative library that supports '@grpc/grpc-js' or fork the package.

affects: >=1.0.0

gotchaAuthentication action is called for every gRPC request, but if the header is missing, it may throw 'Invalid accessToken' error.

fix

Ensure the authentication action handles missing headers gracefully or set 'authentication' to undefined if not needed.

affects: >=1.0.0

breakingv0.x to v1.0 changed the export from a class to a factory function. Direct instantiation with 'new' will fail.

fix

Update code to call GrpcService({...}) instead of new GrpcService(...).

affects: <1.0.0

Errors

Common errors & fixes

TypeError: GrpcService is not a constructor

Using 'new GrpcService()' in v1.x, but GrpcService is a factory function.

fix

Change to GrpcService({...}) without 'new'.

Error: ENOENT: no such file or directory, open 'protos/helloworld.proto'

Relative path provided to 'directory' option.

fix

Use an absolute path: path.resolve(__dirname, 'protos').

Error: Cannot find module 'grpc'

Missing dependency 'grpc' (legacy package) is not installed.

fix

Run 'npm install grpc' or switch to '@grpc/grpc-js' and update the package.

Error: 2 UNKNOWN: Method not found: /helloworld.Greeter/sayHello

Alias mapping is incorrect or proto file definition mismatched.

fix

Verify proto service and package names exactly match 'aliases' key (case-sensitive).

Upgrade

Version history

1.2.5latest on npm

Audit

Dependencies

moleculer-webrequiredRequired peer dependency; provides API Gateway that the mixin extends.

grpcoptionalPossible runtime dependency for gRPC server (if not using @grpc/grpc-js).

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/brunonunes/moleculer-grpc-api ↗

packagemoleculer-grpc-api ↗

homepagehttps://github.com/brunonunes/moleculer-grpc-api#readme ↗