{"id":48108,"library":"grpclb","title":"grpclb","description":"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.","status":"active","version":"1.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/edvardchen/grpclb","tags":["javascript"],"install":[{"cmd":"npm install grpclb","lang":"bash","label":"npm"},{"cmd":"yarn add grpclb","lang":"bash","label":"yarn"},{"cmd":"pnpm add grpclb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; grpc package needed for gRPC functionality. Must be installed separately to avoid duplicate copies.","package":"grpc","optional":false}],"imports":[{"note":"ESM default import works; CommonJS require is also possible but shown as ESM in docs.","wrong":"const register = require('grpclb').register","symbol":"register","correct":"import { register } from 'grpclb'"},{"note":"Used for dynamic gRPC code; exported named.","wrong":"","symbol":"createGrpcProxy","correct":"import { createGrpcProxy } from 'grpclb'"},{"note":"Used for static gRPC code; same import path.","wrong":"const createClientPool = require('grpclb').createClientPool","symbol":"createClientPool","correct":"import { createClientPool } from 'grpclb'"}],"quickstart":{"code":"import { register } from 'grpclb';\nimport grpc from 'grpc';\n\nconst server = new grpc.Server();\n// ... add service to server\n\nasync function main() {\n  const revoke = await register({\n    server,\n    etcdKV: { key: '/services/myapp', value: 'localhost:50051' },\n    ttl: 10,\n    etcdHosts: ['localhost:2379'],\n  });\n  server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => {\n    server.start();\n  });\n}\nmain();","lang":"typescript","description":"Registers a gRPC server with etcd for service discovery. Uses the register function with server instance, etcd key-value pair, and TTL."},"warnings":[{"fix":"Install grpc separately: npm install grpc","message":"grpc must be installed as a peer dependency; otherwise Channel's second argument must be a ChannelCredentials error occurs.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Use grpc (C-based) or check if grpclb works with @grpc/grpc-js (not officially supported).","message":"When 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).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Migrate to @grpc/grpc-js; note that grpclb may not work without modifications.","message":"The grpc package is deprecated; consider using @grpc/grpc-js instead.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Set ETCD_HOSTS env or pass etcdHosts option.","message":"Etcd hosts must be set as environment variable ETCD_HOSTS or passed in options. If missing, connection fails silently.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use createClientPool for static generated code.","message":"createGrpcProxy only works with dynamically loaded proto files (loadSync). It does not support static generated code.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'1.3.4':17 'avoid':46 'balanc':7,32 'client':26,37 'client-sid':25 'code':56 'copi':49 'current':20 'depend':43 'differenti':40 'discoveri':15 'duplic':47 'dynam':52 'etcd':12 'frequent':62 'grpc':5,45,48,55 'grpclb':1,2 'integr':10 'javascript':34,64 'key':39 'lightweight':41 'load':6,31 'matur':59 'node.js':9 'packag':57 'peer':42 'pool':38 'provid':24 'proxi':35 'releas':22 'robin':30 'round':29 'round-robin':28 'servic':14 'side':27 'stabl':21 'static':54 'support':50 'updat':63 'version':16 'via':33","created_at":"2026-06-07T16:54:57.642227+00:00","updated_at":"2026-06-07T16:54:57.642227+00:00","problems":[{"fix":"Ensure grpc is installed as peer dependency (npm install grpc) and not nested.","cause":"Duplicate grpc copies; grpclb resolves its own grpc version vs app's version.","error":"TypeError: Channel's second argument must be a ChannelCredentials"},{"fix":"Kill the process using the port or change server port.","cause":"Port already in use; another process or server is running on same port.","error":"Error: listen EADDRINUSE :::50051"},{"fix":"Start etcd server and verify ETCD_HOSTS environment variable or etcdHosts option.","cause":"Etcd not running or unreachable; ETCD_HOSTS not set or wrong.","error":"UnhandledPromiseRejectionWarning: Error: No connection established"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/edvardchen/grpclb#readme","github":"https://github.com/edvardchen/grpclb","docs":null,"changelog":null,"pypi":null,"npm":"grpclb","openapi_spec":null,"status_page":null,"smithery":null,"categories":["infrastructure"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}