Engine.IO Realtime Engine

Common errors

• ERR_REQUIRE_ESM: require() of ES Module path/to/node_modules/engine.io/build/index.mjs not supported.

  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.
  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');`.

• TypeError: engine.Server is not a constructor

  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()`.
  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();`.

• WebSocket connection to 'ws://localhost:3000/' failed: Error during WebSocket handshake: Unexpected response code: 400

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Refactor custom URL parsing logic in your application from `url.parse()` to `new URL()` to align with modern Node.js APIs.
• gotcha 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.
  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).

Install

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

Imports

• Server
  wrong:

  const Server = require('engine.io').Server;

  correct:

  import { Server } from 'engine.io';

  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
  wrong:

  const listen = require('engine.io').listen;

  correct:

  import { listen } from 'engine.io';

  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
  wrong:

  const Socket = require('engine.io').Socket;

  correct:

  import { Socket } from 'engine.io';

  Represents an individual client connection. Instances of `Socket` are emitted by the `Server` and provide methods for sending/receiving data and managing connection state.

Quickstart

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