grpc-core

library1.0.6jsnpmunverified

A minimal Node.js helper library for building gRPC microservices, currently at version 1.0.6 (stable, low release cadence). Provides GrpcServer, GrpcService, and GrpcClient abstractions that simplify exposing class methods as gRPC endpoints. Differentiators: automatic method-to-RPC mapping, private method exclusion (underscore-prefixed), and async support. Requires Node >= 8.10 and depends on the `grpc` package. Less flexible than full-featured frameworks like `@grpc/proto-loader` + `@grpc/grpc-js`, but offers a cleaner OOP pattern.

devops

npm install grpc-core

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-CORE

grpc-core

devopsjavascriptv1.0.6

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.

GrpcServer

✓ import { GrpcServer } from 'grpc-core';

✗ const GrpcServer = require('grpc-core').GrpcServer;

ESM and CJS both supported; named export is available. For CJS, use destructured require.

GrpcService

✓ import { GrpcService } from 'grpc-core';

✗ import GrpcService from 'grpc-core';

GrpcService is a named export, not default. Always use destructured import.

GrpcClient

✓ import { GrpcClient } from 'grpc-core';

✗ const { GrpcClient } = require('grpc-core');

Same pattern as others - named export. CJS destructure works, but wrong is minimal; included for completeness.

Shows server creation with GrpcServer and GrpcService, plus client call using GrpcClient.

const { GrpcServer, GrpcService, GrpcClient } = require('grpc-core'); const path = require('path'); // Define a service class HelloService extends GrpcService { constructor() { super({ proto: path.join(__dirname, 'hello.proto'), hooks: {}, middlewares: [] }); } sayHello(ctx) { return { message: 'Hello ' + ctx.request.name }; } } // Start server const server = new GrpcServer({ host: '0.0.0.0', port: 50051, services: [HelloService], onStart: async () => { console.log('Server starting...'); }, onConnected: () => { console.log('Server connected'); } }); server.start(); // Client (in another process) const client = new GrpcClient({ proto: path.join(__dirname, 'hello.proto'), host: 'localhost', port: 50051 }); client.call('sayHello', { name: 'World' }).then(console.log);

Debug

Known issues

gotchaMethods prefixed with underscore (_) are automatically excluded from gRPC service, even if defined in proto file.

fix

Rename methods to not start with underscore if they should be callable.

affects: >=0.0.0

deprecatedThe package depends on 'grpc' (the old, unmaintained package) not '@grpc/grpc-js'. This may cause compatibility issues with newer Node versions.

fix

Consider migrating to '@grpc/grpc-js' and using '@grpc/proto-loader' directly, as grpc-core is not actively updated.

affects: >=1.0.0

gotchaEventEmitter 'start' vs 'on' - In package.json, 'onStart' is a config key, but internally the server emits 'start'. Ensure you use 'onStart' in config, not event listener.

fix

Use the config property 'onStart' when constructing GrpcServer, not server.on('start', ...).

affects: >=1.0.0

gotchaMultiple services on same server require each service to have a unique proto package name, otherwise gRPC will throw 'Already exists' error.

fix

Ensure each .proto file has distinct 'package' declaration.

affects: >=0.0.0

deprecatedThe 'call' method on GrpcClient is synchronous-like but returns a Promise; using it without await or .then may cause unhandled rejections.

fix

Always await client.call() or attach .catch().

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'grpc'

Missing peer dependency grpc package.

fix

Run: npm install grpc

Error: 12 UNIMPLEMENTED: Method not found

Method name mismatch between proto definition and class method, or method is private (underscore prefix).

fix

Check that the method name in proto (camelCase) matches exactly with class method name, and remove leading underscore.

Error: Proto file not found at path

Incorrect relative path to .proto file when constructing GrpcService.

fix

Use path.join(__dirname, 'relative/path/to/file.proto') for correct resolution.

UnhandledPromiseRejectionWarning: Error: connect ECONNREFUSED

Server not running or wrong host/port in client.

fix

Ensure server is started before client, and verify host/port values match.

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

grpcrequiredCore gRPC implementation for Node.js (the original grpc package, not @grpc/grpc-js)

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/m-elbably/grpc-core ↗

packagegrpc-core ↗

homepagehttps://github.com/m-elbably/grpc-core#readme ↗