Server

Exposed by require("socket.io").

Related documentation pages:

• installation
• initialization
• details of the server instance

new Server(httpServer[, options])

• httpServer (http.Server) the server to bind to.
• options (Object)

Works with and without new:

const io = require("socket.io")();
// or
const { Server } = require("socket.io");
const io = new Server();

Available options:

Available options for the underlying Engine.IO server:

More information here.

new Server(port[, options])

• port (Number) a port to listen to (a new http.Server will be created)
• options (Object)

See above for the list of available options.

const io = require("socket.io")(3000, {
  path: "/test",
  serveClient: false,
  // below are engine.IO options
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

new Server(options)

• options (Object)

See above for the list of available options.

const io = require("socket.io")({
  path: "/test",
  serveClient: false,
});

// either
const server = require("http").createServer();

io.attach(server, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.listen(3000);

// or
io.attach(3000, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.sockets

• (Namespace)

An alias for the default (/) namespace.

io.sockets.emit("hi", "everyone");
// is equivalent to
io.of("/").emit("hi", "everyone");

server.serveClient([value])

• value (Boolean)
• Returns Server|Boolean

If value is true the attached server (see Server#attach) will serve the client files. Defaults to true. This method has no effect after attach is called. If no arguments are supplied this method returns the current value.

// pass a server and the `serveClient` option
const io = require("socket.io")(http, { serveClient: false });

// or pass no server and then you can call the method
const io = require("socket.io")();
io.serveClient(false);
io.attach(http);

server.path([value])

• value (String)
• Returns Server|String

Sets the path value under which engine.io and the static files will be served. Defaults to /socket.io. If no arguments are supplied this method returns the current value.

const io = require("socket.io")();
io.path("/myownpath");

// client-side
const socket = io({
  path: "/myownpath"
});

server.adapter([value])

• value (Adapter)
• Returns Server|Adapter

Sets the adapter value. Defaults to an instance of the Adapter that ships with socket.io which is memory based. See socket.io-adapter. If no arguments are supplied this method returns the current value.

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

server.attach(httpServer[, options])

• httpServer (http.Server) the server to attach to
• options (Object)

Attaches the Server to an engine.io instance on httpServer with the supplied options (optionally).

server.attach(port[, options])

• port (Number) the port to listen on
• options (Object)

Attaches the Server to an engine.io instance on a new http.Server with the supplied options (optionally).

server.listen(httpServer[, options])

Synonym of server.attach(httpServer[, options]).

server.listen(port[, options])

Synonym of server.attach(port[, options]).

server.bind(engine)

• engine (engine.Server)
• Returns Server

Advanced use only. Binds the server to a specific engine.io Server (or compatible API) instance.

server.onconnection(socket)

• socket (engine.Socket)
• Returns Server

Advanced use only. Creates a new socket.io client from the incoming engine.io (or compatible API) Socket.

server.of(nsp)

• nsp (String|RegExp|Function)
• Returns Namespace

Initializes and retrieves the given Namespace by its pathname identifier nsp. If the namespace was already initialized it returns it immediately.

const adminNamespace = io.of("/admin");

A regex or a function can also be provided, in order to create namespace in a dynamic way:

const dynamicNsp = io.of(/^\/dynamic-\d+$/).on("connection", (socket) => {
  const newNamespace = socket.nsp; // newNamespace.name === "/dynamic-101"

  // broadcast to all clients in the given sub-namespace
  newNamespace.emit("hello");
});

// client-side
const socket = io("/dynamic-101");

// broadcast to all clients in each sub-namespace
dynamicNsp.emit("hello");

// use a middleware for each sub-namespace
dynamicNsp.use((socket, next) => { /* ... */ });

With a function:

io.of((name, query, next) => {
  // the checkToken method must return a boolean, indicating whether the client is able to connect or not.
  next(null, checkToken(query.token));
}).on("connection", (socket) => { /* ... */ });

server.close([callback])

• callback (Function)

Closes the Socket.IO server. The callback argument is optional and will be called when all connections are closed.

Note: this also closes the underlying HTTP server.

const Server = require("socket.io");
const PORT   = 3030;
const server = require("http").Server();

const io = Server(PORT);

io.close(); // Close current server

server.listen(PORT); // PORT is free to use

io = Server(server);

server.engine.generateId

Overwrites the default method to generate your custom socket id.

The function is called with a node request object (http.IncomingMessage) as first parameter.

const uuid = require("uuid");

io.engine.generateId = (req) => {
  return uuid.v4(); // must be unique across all Socket.IO servers
}