Skip to content
Node clustering library with support for zero downtime reloading
Find file
Latest commit 7d8539d Nov 1, 2015 6 @spion spion Update
fix sticky-listen link


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)


Something went wrong with that request. Please try again.