Registry / devops / ugrpc

ugrpc

JSON →
library1.5.1jsnpmunverified

ugrpc is a gRPC library for Node.js that simplifies the creation of gRPC servers and clients with built-in health check support. Version 1.5.1 provides a concise API for setting up microservice communications using protocol buffers. It uses @grpc/proto-loader for loading .proto files and offers configurable options. The package includes automatic health check service integration, allowing you to define custom health dependencies and update statuses dynamically. It supports both CommonJS and ESM (via TypeScript types) but the examples use require(). Releases are sporadic, and the package is maintained by a single developer. Compared to other gRPC libraries like @grpc/grpc-js, ugrpc abstracts away boilerplate code for server and client initialization, making it suitable for rapid prototyping in microservice environments.

devops
npm install ugrpc
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · UGRPC
U
ugrpc
devopsjavascriptv1.5.1
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.

Server
✓ import { Server } from 'ugrpc'
✗ const Server = require('ugrpc').Server
Package is CommonJS but ships TypeScript types; named import works in both ESM and CJS.
Client
✓ import { Client } from 'ugrpc'
✗ const ugrpc = require('ugrpc'); const Client = ugrpc.Client
Client is a class with static methods like createGrpcClient and createCallOptions.
default import
✓ import ugrpc from 'ugrpc'
✗ const ugrpc = require('ugrpc').default
Package has a default export that includes Server and Client. Using require('ugrpc') returns the whole module, not a default export object.

Demonstrates creating a gRPC server with a sum controller and a client that calls the sum method with a 30-second deadline.

const path = require('path'); const { Server, Client } = require('ugrpc'); // Server const server = new Server({ proto: { packageName: 'calculator', serviceName: 'Calculator', protoPath: path.join(__dirname, 'calculator.proto'), }, host: '0.0.0.0:3000', name: 'calc', controllers: { sum: async (call) => { const { firstNumber, secondNumber } = call.request; return { result: firstNumber + secondNumber }; }, }, }); server.startServer(); // Client const client = Client.createGrpcClient({ host: 'localhost:3000', proto: { packageName: 'calculator', serviceName: 'Calculator', protoPath: path.join(__dirname, 'calculator.proto'), }, }); const options = Client.createCallOptions(30000); client.sum({ firstNumber: 1, secondNumber: 2 }, options, (err, data) => { if (err) console.error(err); else console.log(data.result); });
Debug
Known issues
gotchaThe proto packageName and serviceName must match exactly the names defined in the .proto file, otherwise the client/server will fail to load the service.
fix
Verify that proto.packageName equals the proto package name (without quotes) and proto.serviceName equals the service name.
affects: >=1.0.0
gotchaThe healthcheckStatus property is optional but if provided, the service name must be defined. Omitting name while providing healthcheckStatus may cause unexpected health check behavior.
fix
Always set the name property when using healthcheckStatus, or omit both to use default serving status.
affects: >=1.0.0
gotchaThe createCallOptions static method expects a deadline in milliseconds, but it is easy to mistakenly pass seconds. Using 30 instead of 30000 will result in a very short deadline.
fix
Pass the timeout value in milliseconds (e.g., 30000 for 30 seconds).
affects: >=1.0.0
gotchaControllers must be async functions that return an object, not just modify the call object. The package expects the return value to be automatically sent as the response.
fix
Ensure each controller async function returns a plain object matching the response message fields.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'ugrpc'
ugrpc is not installed or not in node_modules.
fix
Run 'npm install ugrpc' in your project directory.
TypeError: server.startServer is not a function
The Server instance was not created correctly, or the variable is undefined.
fix
Check that Server is imported correctly and instantiated with the new keyword: 'const server = new Server({...});'.
Error: 12 UNIMPLEMENTED: Method not found: calculator.Calculator/sum
The service name or method name in the client request does not match the server's definition.
fix
Verify that the proto file defines the service and method correctly, and that the controller method name (e.g., 'sum') corresponds to the rpc name in lowercase.
Upgrade
Version history
1.5.1latest on npm
Audit
Dependencies
@grpc/grpc-jsrequiredCore gRPC implementation for Node.js, required for server and client functionality.
@grpc/proto-loaderrequiredUsed to load .proto files and generate gRPC service definitions.
Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/khacminh/ugrpc ↗
packageugrpc ↗
homepagehttps://github.com/khacminh/ugrpc#readme ↗
ugrpc — npm install ugrpc · libregistry