Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »

5.2.0 • Public • Published

Build Status NPM version

How to use

const io = require('')(3000);
const redis = require('');
io.adapter(redis({ host: 'localhost', port: 6379 }));

By running with the adapter you can run multiple instances in different processes or servers that can all broadcast and emit events to and from each other.

If you need to emit events to instances from a process, you should use


adapter(uri[, opts])

uri is a string like localhost:6379 where your redis server is located. For a list of options see below.


The following options are allowed:

  • key: the name of the key to pub/sub events on as prefix (
  • host: host to connect to redis on (localhost)
  • port: port to connect to redis on (6379)
  • pubClient: optional, the redis client to publish events on
  • subClient: optional, the redis client to subscribe to events on
  • requestsTimeout: optional, after this timeout the adapter will stop waiting from responses to request (1000ms)

If you decide to supply pubClient and subClient, make sure you use node_redis as a client or one with an equivalent API.


The redis adapter instances expose the following properties that a regular Adapter does not

  • uid
  • prefix
  • pubClient
  • subClient
  • requestsTimeout

RedisAdapter#clients(rooms:Array, fn:Function)

Returns the list of client IDs connected to rooms across all nodes. See Namespace#clients(fn:Function)

io.of('/').adapter.clients((err, clients) => {
  console.log(clients); // an array containing all connected socket ids
io.of('/').adapter.clients(['room1', 'room2'], (err, clients) => {
  console.log(clients); // an array containing socket ids in 'room1' and/or 'room2'
// you can also use'room3').clients((err, clients) => {
  console.log(clients); // an array containing socket ids in 'room3'

RedisAdapter#clientRooms(id:String, fn:Function)

Returns the list of rooms the client with the given ID has joined (even on another node).

io.of('/').adapter.clientRooms('<my-id>', (err, rooms) => {
  if (err) { /* unknown id */ }
  console.log(rooms); // an array containing every room a given id has joined.


Returns the list of all rooms.

io.of('/').adapter.allRooms((err, rooms) => {
  console.log(rooms); // an array containing all rooms (accross every node)

RedisAdapter#remoteJoin(id:String, room:String, fn:Function)

Makes the socket with the given id join the room. The callback will be called once the socket has joined the room, or with an err argument if the socket was not found.

io.of('/').adapter.remoteJoin('<my-id>', 'room1', (err) => {
  if (err) { /* unknown id */ }
  // success

RedisAdapter#remoteLeave(id:String, room:String, fn:Function)

Makes the socket with the given id leave the room. The callback will be called once the socket has left the room, or with an err argument if the socket was not found.

io.of('/').adapter.remoteLeave('<my-id>', 'room1', (err) => {
  if (err) { /* unknown id */ }
  // success

RedisAdapter#remoteDisconnect(id:String, close:Boolean, fn:Function)

Makes the socket with the given id to get disconnected. If close is set to true, it also closes the underlying socket. The callback will be called once the socket was disconnected, or with an err argument if the socket was not found.

io.of('/').adapter.remoteDisconnect('<my-id>', true, (err) => {
  if (err) { /* unknown id */ }
  // success

RedisAdapter#customRequest(data:Object, fn:Function)

Sends a request to every nodes, that will respond through the customHook method.

// on every node
io.of('/').adapter.customHook = (data, cb) => {
  cb('hello ' + data);
// then
io.of('/').adapter.customRequest('john', function(err, replies){
  console.log(replies); // an array ['hello john', ...] with one element per node

Client error handling

Access the pubClient and subClient properties of the Redis Adapter instance to subscribe to its error event:

const redis = require('');
const adapter = redis('localhost:6379');
adapter.pubClient.on('error', function(){});
adapter.subClient.on('error', function(){});

The errors emitted from pubClient and subClient will also be forwarded to the adapter instance:

const io = require('')(3000);
const redis = require('');
io.adapter(redis({ host: 'localhost', port: 6379 }));
io.of('/').adapter.on('error', function(){});

Custom client (eg: with authentication)

If you need to create a redisAdapter to a redis instance that has a password, use pub/sub options instead of passing a connection string.

const redis = require('redis').createClient;
const adapter = require('');
const pub = redis(port, host, { auth_pass: "pwd" });
const sub = redis(port, host, { auth_pass: "pwd" });
io.adapter(adapter({ pubClient: pub, subClient: sub }));

With ioredis client

const io = require('')(3000);
const Redis = require('ioredis');
const cluster = new Redis.Cluster([
    port: 6380,
    host: ''
    port: 6381,
    host: ''
const adapter = require('');
io.adapter(adapter({ pubClient: cluster, subClient: cluster }));


The adapter broadcasts and receives messages on particularly named Redis channels. For global broadcasts the channel name is:

prefix + '#' + namespace + '#'

In broadcasting to a single room the channel name is:

prefix + '#' + namespace + '#' + room + '#'

A number of other libraries adopt this protocol including:






npm i

Downloadsweekly downloads









last publish


  • avatar
  • avatar
Report a vulnerability