node package manager
Loosely couple your services. Use Orgs to version and reuse your code. Create a free org »



Service registry for Node.js on top of etcd

npm install etcd-registry

To install the command line tool

npm install -g etcd-registry
etcd-registry help


var registry = require('etcd-registry');
// Pass the nodes in your cluster in a connection string 
var services = registry(',,');
// Join the registry 
services.join('my-service-name', {port:8080});
// Wait a bit and do a lookup 
services.lookup('my-service-name', function(err, service) {
    console.log('Found the following service:');

Running the above example will produce the following output

Found the following service:
    name: 'my-service-name',
    port: 8080,
    hostname: '',
    host: '',
    url: ''

Full api

  • services = registry(connection-string) Create a new registry client
  • services.join(name, service, [cb]) Join the registry with a new service
  • services.leave([name], [cb]) Leave the registry. Omit the name to remove local services
  • services.lookup(name, cb) Lookup a single service
  • services.list([name], cb) List all services as an array. Omit the name to list all services

Connection string

The connection has the following format


The protocol can be https or http and defaults to http. If you set a namespace all keys will be prefixed with the value. If you do not specify a port in the hosts 4001 will be used (default etcd port).


Services are just JSON documents. etcd-registry will add a default hostname and a couple of other properties. An example of a service document could be:

    name: 'my-service',
    port: 8080,
    hostname: '',       // added by etcd-registry 
    host: '',      // added by etcd-registry 
    url: '' // added by etcd-registry 

These documents are saved in etcd with a TTL of 10s. Every 5s etcd-registry will send a heartbeat for each service to the registry which resets the expiration counter. If possible you should call services.leave() before exiting your service process. Otherwise your service will be garbage collected after (at most) 10s

Fault tolerance

If a operation fails etcd-registry will try another node in the cluster until it has tried everyone. Every once in a while etcd-registry will ping your cluster to see if new machines has joined and update the connection string