Node clustering library with support for zero downtime reloading
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bench log that benchmark is ready Feb 12, 2014
lib add workers and activeWorkers methods Oct 24, 2015
test change activeWorkers API Oct 24, 2015
.gitignore ignore test server module Jan 4, 2015
.npmignore add bench to npmignore Jan 16, 2015 Update Nov 2, 2015
package.json 0.4.5 Oct 24, 2015


Clustering library with support for zero-downtime reloading


If server.js is your regular http server (e.g. express), create cluster.js and add:

var recluster = require('recluster'),
    path = require('path');

var cluster = recluster(path.join(__dirname, 'server.js'));;

process.on('SIGUSR2', function() {
    console.log('Got SIGUSR2, reloading cluster...');

console.log("spawned cluster, kill -s SIGUSR2",, "to reload");

then run it

node cluster.js

To hot-reload the server, simply run

kill -s SIGUSR2 <cluster_pid>

To find out which of the N (= number of cores by default) worker instances you're running from inside server.js, you can use


which is zero-based i.e. 0 <= WORKER_ID < N


var cluster = recluster(file, opt)



Absolute path to the module that defines the server


Number of active workers (default = cores)


Timeout to kill old workers after reload (seconds).

Defaults to 1 second in development, 1 hour in production.


Minimum time between worker respawns when workers die (seconds)


Maximum respawn time (reached via exponential backoff). Set to 0 or undefined to disable exponential backoff.


Use 'listening' for servers (e.g. for express/connect http servers) and 'started' for workers that are immediately ready.

If you want to manually tell recluster when the worker is ready to replace older workers you can use {readyWhen: 'ready'}. Then, to signal readiness from the worker use process.send({cmd: 'ready'})


Array of arguments to pass to the worker


Log various events to stdout. Currently only 'respawns' is supported. Default: {respawns: true}


Which logger to use. Requires a console-compatible log method Default: console


The returned object has the following methods:

Starts the cluster by running child processes


Hot-reloads new code. some of the children will remain active for opt.timeout seconds after reload


Terminates the entire cluster and removes all listeners.


Returns a hash of all worker slots (0 <= WORKER_ID < N). If a worker isn't available at that slot, the value in the hash is null or undefined. Otherwise, the value will be a worker object that is ready to serve requests.


Returns an array of all the workers, including those that are not yet ready or those that will be replaced.

worker cleanup

A server worker can gracefully exit by cleaning up in the 'close' event of its server:

server.on('close', function() {
    // cleanup

Non-server workers can listen for the disconnect command and shut down gracefully before the kill timeout:

process.on('message', function(m) {
    if (m.cmd == 'disconnect') {
        // cleanup

sticky sessions support

If you need sticky sessions e.g. for you can use the experimental companion module sticky-listen, which implements an alternate balancer that distributes the sockets based on the client IP (instead of the regular round-robin one)