Socket.IO

4.8.3 · active · verified Sat Apr 18

Socket.IO is a real-time, bidirectional, event-based communication library that enables low-latency communication between web clients and Node.js servers. It facilitates cross-browser messaging with fallback options for reliable connections, even through proxies and firewalls. The current stable version is 4.8.3, and the package receives regular patch releases for bug fixes, security updates, and dependency maintenance across its ecosystem components.

Common errors

```
Error: Server must be passed to the constructor
```
cause The `Server` constructor was called without an `http.Server` instance or a port number.

fix Initialize the Socket.IO server with `new Server(httpServer)` or `new Server(3000)`.
```
DeprecationWarning: The URL.parse() method is deprecated and will be removed in a future version. Please use the WHATWG URL API.
```
cause An older version of `socket.io` or its dependencies is using the deprecated `url.parse()` function in Node.js.

fix Upgrade `socket.io` to version 4.8.2 or later.
```
Error: connect ECONNREFUSED ::1:3000 (or similar IP/port)
```
cause The client attempted to connect to a Socket.IO server that is not running or is listening on a different host/port.

fix Ensure the Socket.IO server is running and listening on the expected host and port. Verify the client's connection URL matches the server's address.
```
TypeError: socket.on is not a function
```
cause Attempting to register a client-specific event listener on the `io` (Server) instance instead of an individual `socket` instance.

fix Attach client-specific event listeners within the `io.on('connection', (socket) => { ... })` callback, using the `socket` object: `socket.on('eventName', handler)`.
```
WebSocket connection to 'ws://localhost:3000/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400
```
cause This often indicates a Cross-Origin Resource Sharing (CORS) issue or an incorrect Engine.IO path configuration between the client and server.

fix Ensure CORS options are correctly configured on the server-side, e.g., `new Server(httpServer, { cors: { origin: "*", methods: ["GET", "POST"] } })`.

Warnings

breaking A critical security vulnerability (CVE-2026-33151) exists in the `socket.io-parser` dependency, allowing potential resource exhaustion via excessively large binary attachments.
Fix: Upgrade `socket.io` to version 4.8.3 or later to ensure `socket.io-parser` (>=4.2.6) is updated.
gotcha When deploying Socket.IO across multiple Node.js instances behind a load balancer, 'sticky sessions' are required to ensure a client's requests are always routed to the same server instance.
Fix: Configure your load balancer (e.g., Nginx, HAProxy) to use IP-based sticky sessions or a similar mechanism.
deprecated Older Socket.IO versions (or their dependencies) may use Node.js's deprecated `url.parse()` function, leading to deprecation warnings in newer Node.js environments.
Fix: Upgrade to `socket.io@4.8.2` or later, which replaces `url.parse()` with `new URL()`.
gotcha Calling `io.close()` on an already stopped server instance could throw an error, potentially leading to unhandled exceptions.
Fix: Upgrade to `socket.io@4.8.3` or later, which includes a fix for this behavior.

Install

npm install socket.io npm
yarn add socket.io yarn
pnpm add socket.io pnpm

Imports

Server
wrong:
```
const Server = require('socket.io');
```
correct:
```
import { Server } from 'socket.io';
```
While CommonJS is supported, modern Node.js and TypeScript projects typically use ESM.

Quickstart

This code sets up a basic Socket.IO server on port 3000 that listens for client connections. When a client connects, it logs the ID, sends a 'hello' event, listens for 'message' events from that client, and broadcasts them to all connected clients. It also handles client disconnections.

import { Server } from 'socket.io';
import { createServer } from 'http';

const httpServer = createServer();
const io = new Server(httpServer, {
  cors: {
    origin: '*', // Allow all origins for simplicity in quickstart
    methods: ['GET', 'POST']
  }
});

io.on('connection', (socket) => {
  console.log(`User connected: ${socket.id}`);

  socket.emit('hello', `Welcome, ${socket.id}!`);

  socket.on('message', (payload: string) => {
    console.log(`Received message from ${socket.id}: ${payload}`);
    // Broadcast the message to all connected clients
    io.emit('broadcast', `Message from ${socket.id}: ${payload}`);
  });

  socket.on('disconnect', () => {
    console.log(`User disconnected: ${socket.id}`);
  });
});

const PORT = process.env.PORT ?? 3000;
httpServer.listen(PORT, () => {
  console.log(`Socket.IO server listening on port ${PORT}`);
});

view raw JSON →