grpclb

library1.3.4jsnpmunverified

grpclb is a gRPC load balancer for Node.js integrated with etcd for service discovery. Version 1.3.4 is the current stable release. It provides client-side round-robin load balancing via JavaScript Proxy or client pool. Key differentiators: lightweight, peer dependency with grpc avoids duplicate grpc copies, supports both dynamic and static gRPC code. Package is mature but not frequently updated.

infrastructure

npm install grpclb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPCLB

grpclb

infrastructurejavascriptv1.3.4

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.

✓ import { register } from 'grpclb'

✗ const register = require('grpclb').register

ESM default import works; CommonJS require is also possible but shown as ESM in docs.

createGrpcProxy

✓ import { createGrpcProxy } from 'grpclb'

Used for dynamic gRPC code; exported named.

createClientPool

✓ import { createClientPool } from 'grpclb'

✗ const createClientPool = require('grpclb').createClientPool

Used for static gRPC code; same import path.

Registers a gRPC server with etcd for service discovery. Uses the register function with server instance, etcd key-value pair, and TTL.

import { register } from 'grpclb'; import grpc from 'grpc'; const server = new grpc.Server(); // ... add service to server async function main() { const revoke = await register({ server, etcdKV: { key: '/services/myapp', value: 'localhost:50051' }, ttl: 10, etcdHosts: ['localhost:2379'], }); server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => { server.start(); }); } main();

Debug

Known issues

breakinggrpc must be installed as a peer dependency; otherwise Channel's second argument must be a ChannelCredentials error occurs.

fix

Install grpc separately: npm install grpc

affects: >=0.0.0

gotchaWhen using with Node.js gRPC @grpc/grpc-js instead of grpc, import paths and behavior may differ. grpclb is designed for the grpc package (C-based).

fix

Use grpc (C-based) or check if grpclb works with @grpc/grpc-js (not officially supported).

affects: >=0.0.0

deprecatedThe grpc package is deprecated; consider using @grpc/grpc-js instead.

fix

Migrate to @grpc/grpc-js; note that grpclb may not work without modifications.

affects: >=0.0.0

gotchaEtcd hosts must be set as environment variable ETCD_HOSTS or passed in options. If missing, connection fails silently.

fix

Set ETCD_HOSTS env or pass etcdHosts option.

affects: >=0.0.0

gotchacreateGrpcProxy only works with dynamically loaded proto files (loadSync). It does not support static generated code.

fix

Use createClientPool for static generated code.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: Channel's second argument must be a ChannelCredentials

Duplicate grpc copies; grpclb resolves its own grpc version vs app's version.

fix

Ensure grpc is installed as peer dependency (npm install grpc) and not nested.

Error: listen EADDRINUSE :::50051

Port already in use; another process or server is running on same port.

fix

Kill the process using the port or change server port.

UnhandledPromiseRejectionWarning: Error: No connection established

Etcd not running or unreachable; ETCD_HOSTS not set or wrong.

fix

Start etcd server and verify ETCD_HOSTS environment variable or etcdHosts option.

Upgrade

Version history

1.3.4latest on npm

Audit

Dependencies

grpcrequiredPeer dependency; grpc package needed for gRPC functionality. Must be installed separately to avoid duplicate copies.

Agent activity

43 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/edvardchen/grpclb ↗

packagegrpclb ↗

homepagehttps://github.com/edvardchen/grpclb#readme ↗