Server Installation

info

The latest release is currently 4.7.5, released in March 2024.

You can find the release notes here.

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

npm install socket.io

Yarn

yarn add socket.io

pnpm

pnpm add socket.io

To install a specific version:

NPM

npm install socket.io@version

Yarn

yarn add socket.io@version

pnpm

pnpm add socket.io@version

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

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

Yarn

yarn add --optional bufferutil utf-8-validate

pnpm

pnpm add -O 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

npm install eiows

Yarn

yarn add eiows

pnpm

pnpm add 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 µWebSockets.js

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

Installation:

NPM

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

Yarn

yarn add uWebSockets.js@uNetworking/uWebSockets.js#v20.4.0

pnpm

pnpm add uWebSockets.js@uNetworking/uWebSockets.js#v20.4.0

Usage:

const { App } = require("uWebSockets.js");
const { Server } = require("socket.io");

const app = 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 21 packages, of which 6 are maintained by our team:

└─┬ socket.io@4.7.2
  ├─┬ accepts@1.3.8
  │ ├─┬ mime-types@2.1.35
  │ │ └── mime-db@1.52.0
  │ └── negotiator@0.6.3
  ├── base64id@2.0.0
  ├─┬ cors@2.8.5
  │ ├── object-assign@4.1.1
  │ └── vary@1.1.2
  ├─┬ debug@4.3.4
  │ └── ms@2.1.2
  ├─┬ engine.io@6.5.2
  │ ├── @types/cookie@0.4.1
  │ ├─┬ @types/cors@2.8.13
  │ │ └── @types/node@20.4.6 deduped
  │ ├── @types/node@20.4.6
  │ ├── accepts@1.3.8 deduped
  │ ├── base64id@2.0.0 deduped
  │ ├── cookie@0.4.2
  │ ├── cors@2.8.5 deduped
  │ ├── debug@4.3.4 deduped
  │ ├── engine.io-parser@5.2.1
  │ └─┬ ws@8.11.0
  │   ├── UNMET OPTIONAL DEPENDENCY bufferutil@^4.0.1
  │   └── UNMET OPTIONAL DEPENDENCY utf-8-validate@^5.0.2
  ├─┬ socket.io-adapter@2.5.2
  │ └── ws@8.11.0 deduped
  └─┬ socket.io-parser@4.2.4
    ├── @socket.io/component-emitter@3.1.0
    └── debug@4.3.4 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 version	engine.io version	ws version
4.7.x	6.5.x	8.11.x
4.6.x	6.4.x	8.11.x
4.5.x	6.2.x	8.2.x
4.4.x	6.1.x	8.2.x
4.3.x	6.0.x	8.2.x
4.2.x	5.2.x	7.4.x
4.1.x	5.1.x	7.4.x
4.0.x	5.0.x	7.4.x
3.1.x	4.1.x	7.4.x
3.0.x	4.0.x	7.4.x
2.5.x	3.6.x	7.4.x
2.4.x	3.5.x	7.4.x