Redis Streams adapter

How it works

The adapter will use a Redis stream to forward packets between the Socket.IO servers.

The main difference with the existing Redis adapter (which use the Redis Pub/Sub mechanism) is that this adapter will properly handle any temporary disconnection to the Redis server and resume the stream without losing any packets.

info

• by default, a single stream is used for all namespaces (see the streamCount option)
• the maxLen option allows limiting the size of the stream
• unlike the adapter based on the Redis PUB/SUB mechanism, this adapter will properly handle any temporary disconnection to the Redis server and resume the stream
• if connection state recovery is enabled, the sessions will be stored in Redis as a classic key/value pair

tip

This adapter is also compatible with Valkey.

Source code: https://github.com/socketio/socket.io-redis-streams-adapter

Security considerations

The Redis adapter assumes that Redis is part of the trusted internal infrastructure.

Messages exchanged through Redis Streams are not signed, encrypted, or authenticated by the adapter. Anyone able to connect to Redis and publish to the adapter channels may be able to inject packets, spoof inter-server control messages, or send forged events to connected clients. Anyone able to observe Redis traffic or subscribe to the relevant channels may also be able to inspect event payloads.

Redis should therefore not be exposed to untrusted networks or shared with untrusted clients. Avoid sharing the same Redis instance with unrelated applications unless ACLs are properly configured.

Please use Redis ACLs, authentication, TLS, firewall rules, private networking, and dedicated credentials with the minimum required command and channel permissions where appropriate. Avoid sending long-lived secrets or sensitive credentials in event payloads unless the Redis deployment is adequately protected.

Supported features

Feature	socket.io version	Support
Socket management	4.0.0	✅ YES (since version 0.1.0)
Inter-server communication	4.1.0	✅ YES (since version 0.1.0)
Broadcast with acknowledgements	4.5.0	✅ YES (since version 0.1.0)
Connection state recovery	4.6.0	✅ YES (since version 0.1.0)

Installation

npm install @socket.io/redis-streams-adapter redis

Usage

With the redis package

import { createClient } from "redis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = createClient({ url: "redis://localhost:6379" });

await redisClient.connect();

const io = new Server({
  adapter: createAdapter(redisClient)
});

io.listen(3000);

With the redis package and a Redis cluster

import { createCluster } from "redis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = createCluster({
  rootNodes: [
    {
      url: "redis://localhost:7000",
    },
    {
      url: "redis://localhost:7001",
    },
    {
      url: "redis://localhost:7002",
    },
  ],
});

await redisClient.connect();

const io = new Server({
  adapter: createAdapter(redisClient)
});

io.listen(3000);

With the ioredis package

import { Redis } from "ioredis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = new Redis();

const io = new Server({
  adapter: createAdapter(redisClient)
});

io.listen(3000);

With the ioredis package and a Redis cluster

import { Cluster } from "ioredis";
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-streams-adapter";

const redisClient = new Cluster([
  {
    host: "localhost",
    port: 7000,
  },
  {
    host: "localhost",
    port: 7001,
  },
  {
    host: "localhost",
    port: 7002,
  },
]);

const io = new Server({
  adapter: createAdapter(redisClient)
});

io.listen(3000);

Options

Name	Description	Default value
streamName	The name of the Redis stream.	socket.io
streamCount	The number of streams to use to scale horizontally.	1
channelPrefix	The prefix of the Redis PUB/SUB channels used to communicate between the nodes.	socket.io
useShardedPubSub	Whether to use sharded PUB/SUB (added in Redis 7.0) to communicate between the nodes.	false
maxLen	The maximum size of the stream. Almost exact trimming (~) is used.	10_000
readCount	The number of elements to fetch per XREAD call.	100
blockTimeInMs	The number of ms before the XREAD call times out.	5_000
sessionKeyPrefix	The prefix of the key used to store the Socket.IO session, when the connection state recovery feature is enabled.	sio:session:
onlyPlaintext	Whether the transmitted data contains only JSON-serializable objects without binary data (Buffer, ArrayBuffer, etc.).	false

Common questions

Do I still need to enable sticky sessions when using the Redis Streams adapter?

Yes. Failing to do so will result in HTTP 400 responses (you are reaching a server that is not aware of the Socket.IO session).

More information can be found here.

What happens when the Redis server is down?

Unlike the classic Redis adapter, this adapter will properly handle any temporary disconnection to the Redis server and resume the stream without losing any packets.

Latest releases

Version	Release date	Release notes	Diff
0.3.0	February 2026	link	0.2.3...0.3.0
0.2.3	November 2025	link	0.2.2...0.2.3
0.2.1	March 2024	link	0.2.0...0.2.1
0.2.0	February 2024	link	0.1.0...0.2.0
0.1.0	April 2023	link

Complete changelog