Skip to main content
Version: 4.x

Server Installation

Prerequisites#

Please make sure that Node.js is installed on your system. The current Long Term Support (LTS) release is an ideal starting point, see here.

info

At least Node.js 10 is needed, older versions are not supported anymore.

Installation#

To install the latest release:

npm install socket.io

To install a specific version:

npm install socket.io@version

Latest releases#

Additional packages#

By default, Socket.IO use the WebSocket server provided by the ws package.

There are 2 optional packages that can be installed alongside this package. These packages are binary add-ons which improve certain operations. Prebuilt binaries are available for the most popular platforms so you don't necessarily need to have a C++ compiler installed on your machine.

  • bufferutil: Allows to efficiently perform operations such as masking and unmasking the data payload of the WebSocket frames.
  • utf-8-validate: Allows to efficiently check if a message contains valid UTF-8 as required by the spec.

To install those packages:

npm install --save-optional bufferutil utf-8-validate

Please note that these packages are optional, the WebSocket server will fallback to the Javascript implementation if they are not available. More information can be found here.

Other WebSocket server implementations#

Any Websocket server implementation which exposes the same API as ws (notably the handleUpgrade method) can be used.

For example, you can use the eiows package, which is a fork of the (now deprecated) uws package:

npm install eiows

And then use the wsEngine option:

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

This implementation "allows, but doesn't guarantee" significant performance and memory-usage improvements over the default implementation. As usual, please benchmark it against your own usage.

Usage with uWebSocket.js#

Starting with version 4.4.0, a Socket.IO server can now bind to a uWebSocket.js server.

Installation:

npm install uWebSockets.js@uNetworking/uWebSockets.js#v20.4.0

Usage:

const { App } = require("uWebSockets.js");const { Server } = require("socket.io");
const app = new App();const io = new Server();
io.attachApp(app);
io.on("connection", (socket) => {  // ...});
app.listen(3000, (token) => {  if (!token) {    console.warn("port already in use");  }});

Miscellaneous#

Dependency tree#

A basic installation of the server includes 23 packages:

└─┬ socket.io@4.4.1  ├─┬ accepts@1.3.7  │ ├─┬ mime-types@2.1.34  │ │ └── mime-db@1.51.0  │ └── negotiator@0.6.2  ├── base64id@2.0.0  ├─┬ debug@4.3.3  │ └── ms@2.1.2  ├─┬ engine.io@6.1.1  │ ├── @types/cookie@0.4.1  │ ├── @types/cors@2.8.12  │ ├── @types/node@17.0.8  │ ├── accepts@1.3.7 deduped  │ ├── base64id@2.0.0 deduped  │ ├── cookie@0.4.1  │ ├─┬ cors@2.8.5  │ │ ├── object-assign@4.1.1  │ │ └── vary@1.1.2  │ ├── debug@4.3.3 deduped  │ ├─┬ engine.io-parser@5.0.2  │ │ └── base64-arraybuffer@1.0.1  │ └─┬ ws@8.2.3  │   ├── UNMET OPTIONAL DEPENDENCY bufferutil@^4.0.1  │   └── UNMET OPTIONAL DEPENDENCY utf-8-validate@^5.0.2  ├── socket.io-adapter@2.3.3  └─┬ socket.io-parser@4.0.4    ├── @types/component-emitter@1.2.11    ├── component-emitter@1.3.0    └── debug@4.3.3 deduped
info

The type declarations for 3rd party packages are included, in order to ease the use of the library for TypeScript users (but at the cost of a slightly-larger package).

See also: https://github.com/microsoft/types-publisher/issues/81#issuecomment-234051345

Transitive versions#

The engine.io package brings the engine that is responsible for managing the low-level connections (HTTP long-polling or WebSocket). See also: How it works

socket.io versionengine.io versionws version
4.4.x6.1.x8.2.x
4.3.x6.0.x8.2.x
4.2.x5.2.x7.4.x
4.1.x5.1.x7.4.x
4.0.x5.0.x7.4.x
3.1.x4.1.x7.4.x
3.0.x4.0.x7.4.x
2.4.x3.5.x7.4.x