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.
Socket
✓ import { Socket } from 'engine.io-client';
✗ import Socket from 'engine.io-client'; // Socket is a named export, not default
For ESM environments (modern Node.js, bundlers with ES Modules configured).
Socket
✓ const { Socket } = require('engine.io-client');
✗ const Socket = require('engine.io-client'); // Returns an object with Socket as a property
For CommonJS environments (Node.js versions prior to native ESM support, or when using bundlers like Browserify with CJS).
eio
✓ <script src="/path/to/engine.io.js"></script>
<script>
const socket = eio('ws://localhost');
</script>
✗ import { eio } from 'engine.io-client'; // 'eio' is a global in standalone build, not an export
When using the standalone browser build (`engine.io.js`) which exposes `eio` globally.
SocketWithoutUpgrade, XHR, WebSocket
✓ import { SocketWithoutUpgrade, XHR, WebSocket } from 'engine.io-client';
Named exports for advanced usage like custom transport implementations or tree-shaking specific transports since v6.6.0.
Demonstrates a basic Engine.IO client and server interaction, sending a message and receiving an echo.
import { Socket } from 'engine.io-client';
import { Server } from 'engine.io';
import http from 'http';
const httpServer = http.createServer();
const eioServer = new Server(httpServer);
eioServer.on('connection', (serverSocket) => {
console.log(`Server: Client connected: ${serverSocket.id}`);
serverSocket.on('message', (data) => {
console.log(`Server: Received message from ${serverSocket.id}: ${data}`);
serverSocket.send(`Echo: ${data}`);
});
serverSocket.on('close', (reason, description) => {
console.log(`Server: Client ${serverSocket.id} disconnected: ${reason} - ${description}`);
});
});
httpServer.listen(3000, () => {
console.log('Engine.IO server listening on port 3000');
// Client-side code
const clientSocket = new Socket('ws://localhost:3000');
clientSocket.on('open', () => {
console.log('Client: Connection opened!');
clientSocket.send('Hello from client!');
clientSocket.on('message', (data) => {
console.log(`Client: Received message: ${data}`);
if (data === 'Echo: Hello from client!') {
clientSocket.close();
}
});
clientSocket.on('close', () => {
console.log('Client: Connection closed!');
});
clientSocket.on('error', (err) => {
console.error('Client: Error!', err);
});
});
});
Debug
Known issues
breakingEngine.IO v4 (and subsequently Socket.IO v3) introduced significant breaking changes including a reversal of the heartbeat mechanism (server now sends ping) and changes to packet encoding. Clients from v3 will not be able to connect to v4 servers and vice-versa.fixEnsure both client and server are running compatible major versions of Engine.IO (or Socket.IO). For live upgrades, run v3 and v4 servers in parallel and route traffic based on EIO query parameter, path, or domain.
affects: >=4.0.0
breakingThe `perMessageDeflate` WebSocket option is now disabled by default since Engine.IO v4 to prevent excessive memory usage in production deployments.fixIf `perMessageDeflate` is required for compression, it must be explicitly re-enabled in your server configuration, understanding the potential memory overhead.
affects: >=4.0.0
breakingA critical vulnerability (CVE-2026-33151) in `socket.io-parser` (a core dependency/peer of the Socket.IO ecosystem) allows a specially crafted packet to cause server memory exhaustion, leading to Denial of Service. While `engine.io-client` itself doesn't directly implement the parser, it's crucial to upgrade all related Socket.IO components.fixUpgrade `socket.io-parser` to version 4.2.6, 3.4.4, 3.3.5, or newer, and ensure your `engine.io-client` and `engine.io` dependencies are up-to-date, as recent releases (e.g., `engine.io-client@6.6.4`) include dependency bumps for `ws` and `debug` that are part of the overall security posture.
affects: <4.2.6 (for socket.io-parser v4), <3.4.4 (for socket.io-parser v3), <3.3.5 (for socket.io-parser v3)
gotchaWhen using `extraHeaders` for authentication or custom data, these headers are only sent during HTTP polling requests in the browser, not during WebSocket upgrade requests due to browser WebSocket API limitations.fixFor browser clients needing headers with WebSockets, use the `transportOptions` attribute for the polling transport, or consider alternative authentication methods like query parameters or cookies that are handled by the browser's native WebSocket API. Note that `transportOptions` for WebSockets will still not send `extraHeaders` in the upgrade request.
affects: >=1.0.0
gotchaAlthough `engine.io-client` can technically be used without Socket.IO, it is generally not recommended for most application development. Engine.IO provides only the basic transport layer, lacking features like multiplexing, automatic reconnection, and acknowledgment callbacks that Socket.IO offers.fixFor most real-world applications, especially those requiring robust client-server communication with automatic handling of various network conditions and application-level events, use the `socket.io-client` package which builds upon `engine.io-client`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'engine.io-client'
The package is not installed or the path is incorrect.
fixRun `npm install engine.io-client` or `yarn add engine.io-client` to install the package. Verify the import path is correct.
TypeError: (0 , engine_io_client__WEBPACK_IMPORTED_MODULE_0__.Socket) is not a constructor
Attempting to use `Socket` as a default import when it is a named export, common in ESM environments.
fixChange `import Socket from 'engine.io-client';` to `import { Socket } from 'engine.io-client';` ReferenceError: eio is not defined
The `eio` global function is only available when using the standalone `engine.io.js` browser bundle directly, not when importing the npm package in a module environment.
fixIf using npm and a bundler, `import { Socket } from 'engine.io-client';` is the correct approach. If targeting browsers without a module bundler, ensure `engine.io.js` is loaded via a `<script>` tag before your application code. RangeError: Maximum call stack size exceeded
This can sometimes occur with large binary data transfers or very rapid message sending, especially if `socket.io-parser` is an older, vulnerable version.
fixUpgrade `engine.io-client` and its transitive dependencies, particularly `socket.io-parser`, to the latest versions to benefit from fixes like the binary attachment limit (CVE-2026-33151). Consider implementing flow control or message throttling on the application layer for very high-volume data streams.
Audit
Dependencies
wsrequiredPrimary WebSocket transport implementation. Regularly updated for security and performance.
debugrequiredUsed for internal logging and debugging. Can be enabled via the DEBUG environment variable.
@socket.io/component-emitterrequiredProvides a robust event emitter implementation.
engine.io-parserrequiredHandles the encoding and decoding of Engine.IO packets.