Last Updated: February 25, 2016
· icflorescu

Clustering Node.js applications

Due to their event-driven, non-blocking IO model, Node.js web applications can be incredibly fast and responsive, because your main thread is free to process other requests while executing background operations (such as database queries, image processing, filesystem operations, calling other services, etc.).

However, a single instance of Node is always running in a single thread, and there are times when you might want to take advantage of multi-core systems, in order to make your fast app even faster. The good news is you can easily load-balance incoming connections across multiple processes using the cluster module, with virtually no change in your existing codebase.

Clustering Node.js applications

Suppose your app entry point is an app.coffee file looking like this:

express = require 'express'
http    = require 'http'

app     = express()

app.set 'port', env.PORT or 3000


# Start listening for incoming requests
http.createServer(app).listen app.get('port'), ->
  console.log "Express server listening on port #{app.get('port')}"

Normally, you'd start your app with something like $ coffee app.coffee.

To enable clustering, simply add a start.js file similar to this one:

var cluster = require('cluster'),
    env = process.env,

cluster.on('exit', function(worker) {
  if (env.NODE_ENV == 'production') {

if (cluster.isMaster) {
  for (i = 0; i < env.CLUSTER_WORKERS; i++) {
} else {

Don't forget to set the CLUSTER_WORKERS environment variable to your desired value (i.e. the number of cores you want to allocate, or less if you want to keep some of them for other tasks), and simply start your app with $ node start.js.

In the above code sample I'm also using a (very) simplistic approach to automatically restart the workers in the event of uncaught errors.

This also makes sense for apps hosted on Heroku, since word has it that each Heroku dyno has four virtual CPU cores.
I didn't test on other PaaS providers, though.

Say Thanks

2 Responses
Add your response



over 1 year ago ·

Thanks for reading, Eduardo!

over 1 year ago ·