Server Initialization

Once you have installed the Socket.IO server library, you can now init the server. The complete list of options can be found here.

Syntax

CommonJS

const httpServer = require("http").createServer();
const io = require("socket.io")(httpServer, {
  // ...
});

io.on("connection", (socket) => {
  // ...
});

httpServer.listen(3000);

ES modules

Please see here for enabling ECMAScript modules in your Node.js project.

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

const httpServer = createServer();
const io = new Server(httpServer, {
  // ...
});

io.on("connection", (socket) => {
  // ...
});

httpServer.listen(3000);

TypeScript

First, you need to install the types: npm i --save-dev @types/socket.io

import { createServer } from "http";
import Server = require("socket.io");
import { Socket } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  // ...
});

io.on("connection", (socket: Socket) => {
  // ...
});

httpServer.listen(3000);

Initialization

Standalone

const options = { /* ... */ };
const io = require('socket.io')(options);

io.on('connection', socket => { /* ... */ });

io.listen(3000);

You can also pass the port as the first argument:

const options = { /* ... */ };
const io = require('socket.io')(3000, options);

io.on('connection', socket => { /* ... */ });

This implicitly starts a Node.js HTTP server, which can be accessed through io.httpServer.

Attached to an existing HTTP server

const server = require('http').createServer();
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

With HTTPS:

const fs = require('fs');
const server = require('https').createServer({
  key: fs.readFileSync('/tmp/key.pem'),
  cert: fs.readFileSync('/tmp/cert.pem')
});
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

With Express

const app = require('express')();
const server = require('http').createServer(app);
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

More information here.

With Koa

const app = require('koa')();
const server = require('http').createServer(app.callback());
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

More information here.

Notable options

The complete list of options can be found here. Here are those which you will most likely use:

perMessageDeflate option

Default value: false

The WebSocket server provided by the ws package supports the permessage-deflate extension, which enables the client and server to negotiate a compression algorithm and its parameters, and then selectively apply it to the data payloads of each WebSocket message.

Starting from Socket.IO v2.4.0 (and in v3), this extension is now disabled by default, because it adds a significant overhead in terms of performance and memory consumption (and the ws maintainers suggest to only enable it if it is really needed).

For previous versions, you can disable it with:

const io = require('socket.io')({
  perMessageDeflate: false
});

maxHttpBufferSize option

Default value: 1e6

This defines how many bytes a single message can be, before closing the socket. It defaults to 1e6 (1MB). You may increase or decrease this value depending on your needs.

const io = require('socket.io')({
  maxHttpBufferSize: 1e8
});

It matches the maxPayload option of the ws package.