Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
io
✓ import { io } from 'socket.io-client';
✗ const io = require('socket.io-client');
Since v3, `io` is a named export. CommonJS users should destructure it: `const { io } = require('socket.io-client');`.
Socket
✓ import type { Socket } from 'socket.io-client';
Used for TypeScript type inference of the client socket instance.
Manager
✓ import { Manager } from 'socket.io-client';
✗ const Manager = require('socket.io-client').Manager;
For advanced use cases, allowing manual control over connection pooling and options. Not typically needed for basic usage.
Establishes a connection to a Socket.IO server, sends a message upon connection, listens for incoming messages, and handles connection lifecycle events like disconnects and errors.
import { io, Socket } from 'socket.io-client';
// Connect to a Socket.IO server running on localhost:3000
const socket: Socket = io('http://localhost:3000');
// Event listener for successful connection
socket.on('connect', () => {
console.log(`Connected to the server with ID: ${socket.id}`);
// Emit a 'greeting' event to the server
socket.emit('greeting', 'Hello from the client!');
});
// Event listener for incoming 'message' events from the server
socket.on('message', (data: string) => {
console.log('Received message:', data);
});
// Event listener for disconnection
socket.on('disconnect', (reason: Socket.DisconnectReason) => {
console.log(`Disconnected from the server: ${reason}`);
});
// Event listener for connection errors
socket.on('connect_error', (error: Error) => {
console.error('Connection error:', error.message);
});
// Manually disconnect after 15 seconds (optional)
setTimeout(() => {
if (socket.connected) {
console.log('Manually disconnecting after 15 seconds...');
socket.disconnect();
}
}, 15000);
Debug
Known issues
breakingMajor protocol changes between Socket.IO v2, v3, and v4. A client from v2/v3 will not connect to a v4 server, and vice versa. Ensure your client and server versions match the major version (e.g., v4 client with v4 server).fixUpgrade both your `socket.io` server package and `socket.io-client` package to matching major versions. Refer to the official migration guides for specifics.
affects: >=3.0.0
breakingSince `socket.io-client` v3, the main `io` function is a named export. This changes how it's imported in both ESM and CommonJS.fixFor ESM, use `import { io } from 'socket.io-client';`. For CommonJS, use `const { io } = require('socket.io-client');`. affects: >=3.0.0
securityA critical vulnerability (CVE-2026-33151) was found in `socket.io-parser` (a dependency), which could lead to denial of service due to an unbounded number of binary attachments. This affects several `socket.io-parser` versions.fixUpgrade `socket.io-client` to version 4.8.3 or higher, or ensure your `socket.io-parser` dependency is updated to 4.2.6, 3.4.4, or 3.3.5, depending on your major version of Socket.IO.
affects: <4.2.6 (for v4), <3.4.4 (for v3), <3.3.5 (for v2)
gotchaWhen connecting from a browser to a server on a different origin (domain, port, or protocol), you must configure Cross-Origin Resource Sharing (CORS) on the server-side. Otherwise, connection attempts will be blocked by the browser.fixOn your Socket.IO server, configure the `cors` option in `new Server(httpServer, { cors: { origin: "*", methods: ["GET", "POST"] } });` (or specify specific origins/methods). affects: All versions
Errors
Common errors & fixes
io is not a function
Attempting to import `io` as a default export in CommonJS or an incorrect named import.
fixFor CommonJS, use `const { io } = require('socket.io-client');`. For ESM, ensure `import { io } from 'socket.io-client';`. WebSocket connection to 'ws://localhost:3000/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400
The Socket.IO server is either not running, not listening on the specified port/path, or the client/server major versions are mismatched.
fixVerify the server is running and accessible. Check the server logs for errors. Ensure `socket.io-client` and `socket.io` server versions are compatible (e.g., both v4).
Access to XMLHttpRequest at 'http://localhost:3000/socket.io/?EIO=4&transport=polling&t=N24sJ1p' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
The client application's origin does not match the server's origin, and the server's CORS policy does not allow the client's origin.
fixConfigure CORS on your Socket.IO server to allow requests from the client's origin. For example: `new Server(httpServer, { cors: { origin: "http://localhost:5173", methods: ["GET", "POST"] } });` Audit
Dependencies
engine.io-clientrequiredProvides the low-level transport layer for Socket.IO, handling connection establishment and data framing.
wsoptionalUsed by engine.io-client as the WebSocket transport implementation in Node.js environments.