Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ import { Server } from 'engine.io';
✗ const Server = require('engine.io').Server;
Since Engine.IO v6, the library offers both CommonJS and ES Modules exports. Prefer named imports for clarity and tree-shaking when using ESM. The `require('engine.io')` pattern is for CommonJS.
listen
✓ import { listen } from 'engine.io';
✗ const listen = require('engine.io').listen;
The `listen` function provides a convenient way to quickly set up an Engine.IO server on a given port, abstracting HTTP server creation. Use named import for ESM.
Socket
✓ import { Socket } from 'engine.io';
✗ const Socket = require('engine.io').Socket;
Represents an individual client connection. Instances of `Socket` are emitted by the `Server` and provide methods for sending/receiving data and managing connection state.
This quickstart demonstrates how to set up an Engine.IO server, attach it to an existing Node.js HTTP server, and handle client connections, messages, and disconnections. It includes basic error handling and illustrates both sending and receiving data.
import { Server } from 'engine.io';
import * as http from 'http';
// Create a basic HTTP server
const httpServer = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end('Engine.IO is running!\n');
});
// Attach Engine.IO to the HTTP server
const eioServer = new Server({
pingInterval: 1000, // Client pings server every 1 second
pingTimeout: 500 // Server considers client disconnected if no ping for 0.5 seconds
});
eioServer.attach(httpServer);
// Handle connections
eioServer.on('connection', (socket) => {
console.log(`Client connected: ${socket.id}`);
// Send a message to the client
socket.send('Hello from Engine.IO server!');
// Listen for messages from the client
socket.on('message', (data) => {
console.log(`Received message from ${socket.id}: ${data}`);
// Echo the message back to the client
socket.send(`Server received: ${data}`);
});
// Handle client disconnection
socket.on('close', (reason, description) => {
console.log(`Client ${socket.id} disconnected. Reason: ${reason}, Description: ${description}`);
});
// Handle errors
socket.on('error', (err) => {
console.error(`Error on socket ${socket.id}:`, err);
});
});
// Start the HTTP server
const PORT = process.env.PORT || 3000;
httpServer.listen(PORT, () => {
console.log(`Engine.IO server listening on http://localhost:${PORT}`);
console.log('Connect with an Engine.IO client, e.g., in browser: new eio.Socket(\'ws://localhost:3000\');');
});
Debug
Known issues
breakingA critical security vulnerability (CVE-2026-33151) affecting `socket.io-parser` has been patched across several `socket.io-parser` versions (>=3.3.5, >=3.4.4, >=4.2.6). While `engine.io` itself does not directly depend on `socket.io-parser`, this module is a fundamental component of the broader Socket.IO ecosystem, including setups where `engine.io` is used as a foundation for `socket.io`. The vulnerability addresses a limit on binary attachments to prevent potential denial-of-service or memory exhaustion attacks. Users running `socket.io` should ensure their `socket.io-parser` dependency is updated to mitigate this risk.fixUpgrade your `socket.io` package to a version that bundles a patched `socket.io-parser` (e.g., `socket.io@4.8.3` or newer). Consult the official Socket.IO release notes for precise version requirements.
affects: <=4.8.2 of `socket.io` (depending on the specific `socket.io-parser` version bundled)
gotchaNode.js's `url.parse()` function has been deprecated in favor of the `new URL()` constructor. While `engine.io`'s internal handling should be updated, applications leveraging `engine.io` that manually parse URLs using `url.parse()` should migrate to `new URL()` to avoid deprecation warnings and ensure future compatibility, especially with newer Node.js versions.fixRefactor custom URL parsing logic in your application from `url.parse()` to `new URL()` to align with modern Node.js APIs.
affects: All versions when used with Node.js 14+.
gotchaThe `engine.io` library ships with both CommonJS (CJS) and ES Module (ESM) exports. The provided README examples predominantly use CJS `require()`. When integrating into an ES Module project, direct named `import { Server } from 'engine.io';` should be used. Mixing `require()` with `import` statements or incorrect import paths in ESM projects can lead to 'ERR_REQUIRE_ESM' or 'default is not a constructor' errors.fixFor ES Module projects, ensure your `package.json` has `"type": "module"` (or use `.mjs` file extensions) and use `import { Server } from 'engine.io';`. For CommonJS projects, stick to `const { Server } = require('engine.io');` (or use `.cjs` file extensions). affects: >=6.0.0 (when dual package support was likely introduced), or any modern Node.js project using ESM.
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module path/to/node_modules/engine.io/build/index.mjs not supported.
Attempting to use `require('engine.io')` in an ES Module environment (`"type": "module"` in `package.json`) that does not permit CommonJS `require()` calls for ESM packages, or vice-versa.
fixIf your project is an ESM project, use `import { Server } from 'engine.io';`. If it's a CJS project, ensure `"type": "commonjs"` is set in `package.json` (or remove `type` field) and use `const { Server } = require('engine.io');`. TypeError: engine.Server is not a constructor
Incorrectly importing the `Server` class, often by attempting to use `import engine from 'engine.io'; new engine.Server();` in an ESM project, or `new Server()` when `Server` was not correctly destructured from a CommonJS `require()`.
fixIf using ES Modules, ensure you're using named imports: `import { Server } from 'engine.io';` then `new Server()`. If using CommonJS, use `const { Server } = require('engine.io');` or `const engine = require('engine.io'); new engine.Server();`. WebSocket connection to 'ws://localhost:3000/' failed: Error during WebSocket handshake: Unexpected response code: 400
The client attempted to connect via WebSocket, but the server was either not running, not properly configured to handle the WebSocket upgrade request, or there's a proxy/firewall interfering. This often happens if the `engine.io` server is not attached to an HTTP server, or the path is incorrect.
fixVerify that the `engine.io` server is running and successfully attached to an `http.Server` instance. Ensure the client's connection URL (e.g., `ws://localhost:3000`) correctly points to the server's address and port. Check any reverse proxy configurations or firewall rules that might block WebSocket connections.
Audit
Dependencies
wsrequiredProvides the WebSocket transport layer for Engine.IO. Regularly updated.
@types/wsoptionalTypeScript type definitions for the 'ws' package, explicitly added in Engine.IO v6.6.6.