Engine.IO Client

Common errors

• Error: Cannot find module 'engine.io-client'

  cause The package is not installed or the path is incorrect.
  fix Run `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

  cause Attempting to use `Socket` as a default import when it is a named export, common in ESM environments.
  fix Change `import Socket from 'engine.io-client';` to `import { Socket } from 'engine.io-client';`

• ReferenceError: eio is not defined

  cause 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.
  fix If 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

  cause This can sometimes occur with large binary data transfers or very rapid message sending, especially if `socket.io-parser` is an older, vulnerable version.
  fix Upgrade `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.

Warnings

• breaking Engine.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.
  Fix: Ensure 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.
• breaking The `perMessageDeflate` WebSocket option is now disabled by default since Engine.IO v4 to prevent excessive memory usage in production deployments.
  Fix: If `perMessageDeflate` is required for compression, it must be explicitly re-enabled in your server configuration, understanding the potential memory overhead.
• breaking A 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.
  Fix: Upgrade `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.
• gotcha When 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.
  Fix: For 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.
• gotcha Although `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.
  Fix: For 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`.

Install

• npm install engine.io-client npm
• yarn add engine.io-client yarn
• pnpm add engine.io-client pnpm

Imports

• Socket
  wrong:

  import Socket from 'engine.io-client'; // Socket is a named export, not default

  correct:

  import { Socket } from 'engine.io-client';

  For ESM environments (modern Node.js, bundlers with ES Modules configured).
• Socket
  wrong:

  const Socket = require('engine.io-client'); // Returns an object with Socket as a property

  correct:

  const { Socket } = require('engine.io-client');

  For CommonJS environments (Node.js versions prior to native ESM support, or when using bundlers like Browserify with CJS).
• eio
  wrong:

  import { eio } from 'engine.io-client'; // 'eio' is a global in standalone build, not an export

  correct:

  <script src="/path/to/engine.io.js"></script>
  <script>
    const socket = eio('ws://localhost');
  </script>

  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.

Quickstart

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);
    });
  });
});