{"id":16015,"library":"engine.io-client","title":"Engine.IO Client","description":"Engine.IO Client is the low-level JavaScript client for Engine.IO, providing the foundational transport-based, bidirectional communication layer that powers Socket.IO. As of version 6.6.4, it supports various transports like HTTP long-polling and WebSockets, with recent updates also introducing WebTransport support and features like transport tree-shaking for optimized bundles. The library is actively maintained with regular updates, often coinciding with releases of its server-side counterpart, Engine.IO, and the Socket.IO framework. It differentiates itself by offering a robust, transport-agnostic real-time communication channel, handling connection upgrades and downgrades automatically to ensure persistent connectivity across different network conditions and environments. While it can be used independently for raw real-time communication, it's primarily designed as the underlying mechanism for the more feature-rich Socket.IO client.","status":"active","version":"6.6.4","language":"javascript","source_language":"en","source_url":"https://github.com/socketio/socket.io","tags":["javascript","typescript"],"install":[{"cmd":"npm install engine.io-client","lang":"bash","label":"npm"},{"cmd":"yarn add engine.io-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add engine.io-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Primary WebSocket transport implementation. Regularly updated for security and performance.","package":"ws","optional":false},{"reason":"Used for internal logging and debugging. Can be enabled via the DEBUG environment variable.","package":"debug","optional":false},{"reason":"Provides a robust event emitter implementation.","package":"@socket.io/component-emitter","optional":false},{"reason":"Handles the encoding and decoding of Engine.IO packets.","package":"engine.io-parser","optional":false}],"imports":[{"note":"For ESM environments (modern Node.js, bundlers with ES Modules configured).","wrong":"import Socket from 'engine.io-client'; // Socket is a named export, not default","symbol":"Socket","correct":"import { Socket } from 'engine.io-client';"},{"note":"For CommonJS environments (Node.js versions prior to native ESM support, or when using bundlers like Browserify with CJS).","wrong":"const Socket = require('engine.io-client'); // Returns an object with Socket as a property","symbol":"Socket","correct":"const { Socket } = require('engine.io-client');"},{"note":"When using the standalone browser build (`engine.io.js`) which exposes `eio` globally.","wrong":"import { eio } from 'engine.io-client'; // 'eio' is a global in standalone build, not an export","symbol":"eio","correct":"<script src=\"/path/to/engine.io.js\"></script>\n<script>\n  const socket = eio('ws://localhost');\n</script>"},{"note":"Named exports for advanced usage like custom transport implementations or tree-shaking specific transports since v6.6.0.","symbol":"SocketWithoutUpgrade, XHR, WebSocket","correct":"import { SocketWithoutUpgrade, XHR, WebSocket } from 'engine.io-client';"}],"quickstart":{"code":"import { Socket } from 'engine.io-client';\nimport { Server } from 'engine.io';\nimport http from 'http';\n\nconst httpServer = http.createServer();\nconst eioServer = new Server(httpServer);\n\neioServer.on('connection', (serverSocket) => {\n  console.log(`Server: Client connected: ${serverSocket.id}`);\n  serverSocket.on('message', (data) => {\n    console.log(`Server: Received message from ${serverSocket.id}: ${data}`);\n    serverSocket.send(`Echo: ${data}`);\n  });\n  serverSocket.on('close', (reason, description) => {\n    console.log(`Server: Client ${serverSocket.id} disconnected: ${reason} - ${description}`);\n  });\n});\n\nhttpServer.listen(3000, () => {\n  console.log('Engine.IO server listening on port 3000');\n\n  // Client-side code\n  const clientSocket = new Socket('ws://localhost:3000');\n\n  clientSocket.on('open', () => {\n    console.log('Client: Connection opened!');\n    clientSocket.send('Hello from client!');\n\n    clientSocket.on('message', (data) => {\n      console.log(`Client: Received message: ${data}`);\n      if (data === 'Echo: Hello from client!') {\n        clientSocket.close();\n      }\n    });\n\n    clientSocket.on('close', () => {\n      console.log('Client: Connection closed!');\n    });\n\n    clientSocket.on('error', (err) => {\n      console.error('Client: Error!', err);\n    });\n  });\n});","lang":"typescript","description":"Demonstrates a basic Engine.IO client and server interaction, sending a message and receiving an echo."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If `perMessageDeflate` is required for compression, it must be explicitly re-enabled in your server configuration, understanding the potential memory overhead.","message":"The `perMessageDeflate` WebSocket option is now disabled by default since Engine.IO v4 to prevent excessive memory usage in production deployments.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<4.2.6 (for socket.io-parser v4), <3.4.4 (for socket.io-parser v3), <3.3.5 (for socket.io-parser v3)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install engine.io-client` or `yarn add engine.io-client` to install the package. Verify the import path is correct.","cause":"The package is not installed or the path is incorrect.","error":"Error: Cannot find module 'engine.io-client'"},{"fix":"Change `import Socket from 'engine.io-client';` to `import { Socket } from 'engine.io-client';`","cause":"Attempting to use `Socket` as a default import when it is a named export, common in ESM environments.","error":"TypeError: (0 , engine_io_client__WEBPACK_IMPORTED_MODULE_0__.Socket) is not a constructor"},{"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.","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.","error":"ReferenceError: eio is not defined"},{"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.","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.","error":"RangeError: Maximum call stack size exceeded"}],"ecosystem":"npm"}