{"id":15318,"library":"engine.io","title":"Engine.IO Realtime Engine","description":"Engine.IO is a foundational real-time communication library that underpins Socket.IO, providing the bidirectional connection layer between client and server. It offers robust transport mechanisms to ensure maximum reliability across various network conditions, including proxies, load balancers, and personal firewall software. Currently stable at version 6.6.6, Engine.IO receives updates in alignment with the broader Socket.IO ecosystem, often focusing on bug fixes, dependency updates, and security patches, as seen in recent releases. Its design prioritizes minimal client size and scalability, making it suitable for high-performance applications. Unlike higher-level abstractions, Engine.IO exposes a 100% Node.js core-style API, emphasizing a direct and unopinionated approach to real-time communication without extensive API sugar, allowing developers granular control over the connection lifecycle and underlying transports.","status":"active","version":"6.6.6","language":"javascript","source_language":"en","source_url":"https://github.com/socketio/socket.io","tags":["javascript","typescript"],"install":[{"cmd":"npm install engine.io","lang":"bash","label":"npm"},{"cmd":"yarn add engine.io","lang":"bash","label":"yarn"},{"cmd":"pnpm add engine.io","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the WebSocket transport layer for Engine.IO. Regularly updated.","package":"ws","optional":false},{"reason":"TypeScript type definitions for the 'ws' package, explicitly added in Engine.IO v6.6.6.","package":"@types/ws","optional":true}],"imports":[{"note":"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.","wrong":"const Server = require('engine.io').Server;","symbol":"Server","correct":"import { Server } from 'engine.io';"},{"note":"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.","wrong":"const listen = require('engine.io').listen;","symbol":"listen","correct":"import { listen } from 'engine.io';"},{"note":"Represents an individual client connection. Instances of `Socket` are emitted by the `Server` and provide methods for sending/receiving data and managing connection state.","wrong":"const Socket = require('engine.io').Socket;","symbol":"Socket","correct":"import { Socket } from 'engine.io';"}],"quickstart":{"code":"import { Server } from 'engine.io';\nimport * as http from 'http';\n\n// Create a basic HTTP server\nconst httpServer = http.createServer((req, res) => {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end('Engine.IO is running!\\n');\n});\n\n// Attach Engine.IO to the HTTP server\nconst eioServer = new Server({\n  pingInterval: 1000, // Client pings server every 1 second\n  pingTimeout: 500 // Server considers client disconnected if no ping for 0.5 seconds\n});\neioServer.attach(httpServer);\n\n// Handle connections\neioServer.on('connection', (socket) => {\n  console.log(`Client connected: ${socket.id}`);\n\n  // Send a message to the client\n  socket.send('Hello from Engine.IO server!');\n\n  // Listen for messages from the client\n  socket.on('message', (data) => {\n    console.log(`Received message from ${socket.id}: ${data}`);\n    // Echo the message back to the client\n    socket.send(`Server received: ${data}`);\n  });\n\n  // Handle client disconnection\n  socket.on('close', (reason, description) => {\n    console.log(`Client ${socket.id} disconnected. Reason: ${reason}, Description: ${description}`);\n  });\n\n  // Handle errors\n  socket.on('error', (err) => {\n    console.error(`Error on socket ${socket.id}:`, err);\n  });\n});\n\n// Start the HTTP server\nconst PORT = process.env.PORT || 3000;\nhttpServer.listen(PORT, () => {\n  console.log(`Engine.IO server listening on http://localhost:${PORT}`);\n  console.log('Connect with an Engine.IO client, e.g., in browser: new eio.Socket(\\'ws://localhost:3000\\');');\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade 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.","message":"A 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.","severity":"breaking","affected_versions":"<=4.8.2 of `socket.io` (depending on the specific `socket.io-parser` version bundled)"},{"fix":"Refactor custom URL parsing logic in your application from `url.parse()` to `new URL()` to align with modern Node.js APIs.","message":"Node.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.","severity":"gotcha","affected_versions":"All versions when used with Node.js 14+."},{"fix":"For 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).","message":"The `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.","severity":"gotcha","affected_versions":">=6.0.0 (when dual package support was likely introduced), or any modern Node.js project using ESM."}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"If 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');`.","cause":"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.","error":"ERR_REQUIRE_ESM: require() of ES Module path/to/node_modules/engine.io/build/index.mjs not supported."},{"fix":"If 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();`.","cause":"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()`.","error":"TypeError: engine.Server is not a constructor"},{"fix":"Verify 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.","cause":"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.","error":"WebSocket connection to 'ws://localhost:3000/' failed: Error during WebSocket handshake: Unexpected response code: 400"}],"ecosystem":"npm"}