Version: 4.x

Server options

Socket.IO server options

`adapter`

Default value: require("socket.io-adapter") (in-memory adapter, whose source code can be found here)

CommonJS
ES modules
TypeScript

const { Server } = require("socket.io");
const { createAdapter } = require("@socket.io/redis-adapter");
const { createClient } = require("redis");

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

io.listen(3000);

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

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

io.listen(3000);

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

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

io.listen(3000);

`cleanupEmptyChildNamespaces`

Added in v4.6.0

Default value: false

Whether to remove child namespaces that have no sockets connected to them.

This option might be useful if you create a lot of dynamic namespaces, since each namespace creates its own adapter instance.

With this option enabled (disabled by default), when a socket disconnects from a dynamic namespace and if there are no other sockets connected to it then the namespace will be cleaned up and its adapter will be closed.

`connectTimeout`

Default value: 45000

The number of ms before disconnecting a client that has not successfully joined a namespace.

`parser`

Default value: socket.io-parser

The parser to use. Please see the documentation here.

`path`

Default value: /socket.io/

It is the name of the path that is captured on the server side.

caution

The server and the client values must match (unless you are using a path-rewriting proxy in between).

Server

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  path: "/my-custom-path/"
});

Client

import { io } from "socket.io-client";

const socket = io("https://example.com", {
  path: "/my-custom-path/"
});

`serveClient`

Default value: true

Whether to serve the client files. If true, the different bundles will be served at the following location:

<url>/socket.io/socket.io.js
<url>/socket.io/socket.io.min.js
<url>/socket.io/socket.io.msgpack.min.js

(including their associated source maps)

Low-level engine options

`addTrailingSlash`

Added in v4.6.0

Default value: true

The trailing slash which was added by default can now be disabled:

import { createServer } from "node:http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
addTrailingSlash: false
});

In the example above, the clients can omit the trailing slash and use /socket.io instead of /socket.io/.

`allowEIO3`

Default value: false

Whether to enable compatibility with Socket.IO v2 clients.

`allowRequest`

Default: -

A function that receives a given handshake or upgrade request as its first parameter, and can decide whether to continue or not.

Example:

const io = new Server(httpServer, {
  allowRequest: (req, callback) => {
    const isOriginValid = check(req);
    callback(null, isOriginValid);
  }
});

This can also be used in conjunction with the initial_headers event, to send a cookie to the client:

import { serialize } from "cookie";

const io = new Server(httpServer, {
  allowRequest: async (req, callback) => {
    const session = await fetchSession(req);
    req.session = session;
    callback(null, true);
  }
});

io.engine.on("initial_headers", (headers, req) => {
  if (req.session) {
    headers["set-cookie"] = serialize("sid", req.session.id, { sameSite: "strict" });
  }
});

`allowUpgrades`

Default value: true

Whether to allow transport upgrades.

`cookie`

Default value: -

The list of options that will be forwarded to the cookie module. Available options:

domain
encode
expires
httpOnly
maxAge
path
sameSite
secure

Example:

import { Server } from "socket.io";

const io = new Server(httpServer, {
  cookie: {
    name: "my-cookie",
    httpOnly: true,
    sameSite: "strict",
    maxAge: 86400
  }
});

info

Since Socket.IO v3, there is no cookie sent by default anymore (reference).

`cors`

Default value: -

The list of options that will be forwarded to the cors module. More information can be found here.

Example:

const io = new Server(httpServer, {
  cors: {
    origin: ["https://example.com", "https://dev.example.com"],
    allowedHeaders: ["my-custom-header"],
    credentials: true
  }
});

Available options:

Option	Description
`origin`	Configures the Access-Control-Allow-Origin CORS header.
`methods`	Configures the Access-Control-Allow-Methods CORS header. Expects a comma-delimited string (ex: 'GET,PUT,POST') or an array (ex: `['GET', 'PUT', 'POST']`).
`allowedHeaders`	Configures the Access-Control-Allow-Headers CORS header. Expects a comma-delimited string (ex: 'Content-Type,Authorization') or an array (ex: `['Content-Type', 'Authorization']`). If not specified, defaults to reflecting the headers specified in the request's Access-Control-Request-Headers header.
`exposedHeaders`	Configures the Access-Control-Expose-Headers CORS header. Expects a comma-delimited string (ex: 'Content-Range,X-Content-Range') or an array (ex: `['Content-Range', 'X-Content-Range']`). If not specified, no custom headers are exposed.
`credentials`	Configures the Access-Control-Allow-Credentials CORS header. Set to `true` to pass the header, otherwise it is omitted.
`maxAge`	Configures the Access-Control-Max-Age CORS header. Set to an integer to pass the header, otherwise it is omitted.
`preflightContinue`	Pass the CORS preflight response to the next handler.
`optionsSuccessStatus`	Provides a status code to use for successful `OPTIONS` requests, since some legacy browsers (IE11, various SmartTVs) choke on `204`.

Possible values for the origin option:

Boolean - set origin to true to reflect the request origin, as defined by req.header('Origin'), or set it to false to disable CORS.
String - set origin to a specific origin. For example if you set it to "http://example.com" only requests from "http://example.com" will be allowed.
RegExp - set origin to a regular expression pattern which will be used to test the request origin. If it's a match, the request origin will be reflected. For example the pattern /example\.com$/ will reflect any request that is coming from an origin ending with "example.com".
Array - set origin to an array of valid origins. Each origin can be a String or a RegExp. For example ["http://example1.com", /\.example2\.com$/] will accept any request from "http://example1.com" or from a subdomain of "example2.com".
Function - set origin to a function implementing some custom logic. The function takes the request origin as the first parameter and a callback (which expects the signature err [object], allow [bool]) as the second.

`httpCompression`

Added in v1.4.0

Default value: true

Whether to enable the compression for the HTTP long-polling transport.

Please note that if httpCompression is set to false, the compress flag used when emitting (socket.compress(true).emit(...)) will be ignored when the connection is established with HTTP long-polling requests.

All options from the Node.js zlib module are supported.

Example:

const io = new Server(httpServer, {
  httpCompression: {
    // Engine.IO options
    threshold: 2048, // defaults to 1024
    // Node.js zlib options
    chunkSize: 8 * 1024, // defaults to 16 * 1024
    windowBits: 14, // defaults to 15
    memLevel: 7, // defaults to 8
  }
});

`maxHttpBufferSize`

Default value: 1e6 (1 MB)

This defines how many bytes a single message can be, before closing the socket. You may increase or decrease this value depending on your needs.

const io = new Server(httpServer, {
  maxHttpBufferSize: 1e8
});

It matches the maxPayload option of the ws package.

`perMessageDeflate`

History

Version	Changes
v3.0.0	The permessage-deflate extension is now disabled by default.
v1.4.0	First implementation.

Default value: false

Whether to enable the permessage-deflate extension for the WebSocket transport. This extension is known to add a significant overhead in terms of performance and memory consumption, so we suggest to only enable it if it is really needed.

Please note that if perMessageDeflate is set to false (which is the default), the compress flag used when emitting (socket.compress(true).emit(...)) will be ignored when the connection is established with WebSockets, as the permessage-deflate extension cannot be enabled on a per-message basis.

All options from the ws module are supported:

const io = new Server(httpServer, {
  perMessageDeflate: {
    threshold: 2048, // defaults to 1024

    zlibDeflateOptions: {
      chunkSize: 8 * 1024, // defaults to 16 * 1024
    },

    zlibInflateOptions: {
      windowBits: 14, // defaults to 15
      memLevel: 7, // defaults to 8
    },

    clientNoContextTakeover: true, // defaults to negotiated value.
    serverNoContextTakeover: true, // defaults to negotiated value.
    serverMaxWindowBits: 10, // defaults to negotiated value.

    concurrencyLimit: 20, // defaults to 10
  }
});

`pingInterval`

Default value: 25000

This value is used in the heartbeat mechanism, which periodically checks if the connection is still alive between the server and the client.

The server sends a ping packet every pingInterval ms, and if the client does not answer with a pong within pingTimeout ms, the server considers that the connection is closed.

Similarly, if the client does not receive a ping packet from the server within pingInterval + pingTimeout ms, then the client also considers that the connection is closed.

In both cases, the disconnection reason will be: ping timeout

socket.on("disconnect", (reason) => {
  console.log(reason); // "ping timeout"
});

caution

Using a small value like 1000 (one heartbeat per second) will incur some load on your server, which might become noticeable with a few thousands connected clients.

`pingTimeout`

History

Version	Changes
v4.0.0	`pingTimeout` now defaults to `20000` ms.
v2.1.0	Defaults to `5000` ms.
v1.0.0	Defaults to `60000` ms.

Default value: 20000

See above.

caution

Using a smaller value means that a temporarily unresponsive server might trigger a lot of client reconnections.

On the contrary, using a bigger value means that a broken connection will take longer to get detected (and you might get a warning on React Native if pingInterval + pingTimeout is bigger than 60 seconds).

`transports`

Default value: ["polling", "websocket"]

The low-level transports that are allowed on the server-side.

`upgradeTimeout`

Default value: 10000

This is the delay in milliseconds before an uncompleted transport upgrade is cancelled.

`wsEngine`

Default value: require("ws").Server (source code can be found here)

The WebSocket server implementation to use. Please see the documentation here.

Example:

const io = new Server(httpServer, {
  wsEngine: require("eiows").Server
});

Socket.IO server options​

adapter​

cleanupEmptyChildNamespaces​

connectTimeout​

parser​

path​

caution

serveClient​

Low-level engine options​

addTrailingSlash​

allowEIO3​

allowRequest​

allowUpgrades​

cookie​

info

cors​

httpCompression​

maxHttpBufferSize​

perMessageDeflate​

pingInterval​

caution

pingTimeout​

caution

transports​

upgradeTimeout​

wsEngine​

Socket.IO server options

`adapter`

`cleanupEmptyChildNamespaces`

`connectTimeout`

`parser`

`path`

`serveClient`

Low-level engine options

`addTrailingSlash`

`allowEIO3`

`allowRequest`

`allowUpgrades`

`cookie`

`cors`

`httpCompression`

`maxHttpBufferSize`

`perMessageDeflate`

`pingInterval`

`pingTimeout`

`transports`

`upgradeTimeout`

`wsEngine`