{"id":12049,"library":"socket.io-client","title":"Socket.IO Client","description":"Socket.IO Client is a JavaScript library designed for facilitating real-time, bidirectional, and event-based communication between web clients (browsers or Node.js applications) and a Socket.IO server. It abstracts away the complexities of WebSocket and HTTP long-polling, providing automatic fallback mechanisms, robust reconnection logic, and packet buffering to ensure reliable connectivity even in unstable network conditions. The current stable version, 4.8.3, is part of the actively developed Socket.IO v4 ecosystem. Releases are typically aligned with the server-side `socket.io` package, focusing on bug fixes, performance improvements, and dependency updates. Its key differentiators include its focus on cross-platform compatibility, simplified API for event handling, and built-in reliability features that make it a go-to choice for real-time applications requiring persistent connections.","status":"active","version":"4.8.3","language":"javascript","source_language":"en","source_url":"https://github.com/socketio/socket.io","tags":["javascript","realtime","framework","websocket","tcp","events","client","typescript"],"install":[{"cmd":"npm install socket.io-client","lang":"bash","label":"npm"},{"cmd":"yarn add socket.io-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add socket.io-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the low-level transport layer for Socket.IO, handling connection establishment and data framing.","package":"engine.io-client","optional":false},{"reason":"Used by engine.io-client as the WebSocket transport implementation in Node.js environments.","package":"ws","optional":true}],"imports":[{"note":"Since v3, `io` is a named export. CommonJS users should destructure it: `const { io } = require('socket.io-client');`.","wrong":"const io = require('socket.io-client');","symbol":"io","correct":"import { io } from 'socket.io-client';"},{"note":"Used for TypeScript type inference of the client socket instance.","symbol":"Socket","correct":"import type { Socket } from 'socket.io-client';"},{"note":"For advanced use cases, allowing manual control over connection pooling and options. Not typically needed for basic usage.","wrong":"const Manager = require('socket.io-client').Manager;","symbol":"Manager","correct":"import { Manager } from 'socket.io-client';"}],"quickstart":{"code":"import { io, Socket } from 'socket.io-client';\n\n// Connect to a Socket.IO server running on localhost:3000\nconst socket: Socket = io('http://localhost:3000');\n\n// Event listener for successful connection\nsocket.on('connect', () => {\n  console.log(`Connected to the server with ID: ${socket.id}`);\n  // Emit a 'greeting' event to the server\n  socket.emit('greeting', 'Hello from the client!');\n});\n\n// Event listener for incoming 'message' events from the server\nsocket.on('message', (data: string) => {\n  console.log('Received message:', data);\n});\n\n// Event listener for disconnection\nsocket.on('disconnect', (reason: Socket.DisconnectReason) => {\n  console.log(`Disconnected from the server: ${reason}`);\n});\n\n// Event listener for connection errors\nsocket.on('connect_error', (error: Error) => {\n  console.error('Connection error:', error.message);\n});\n\n// Manually disconnect after 15 seconds (optional)\nsetTimeout(() => {\n  if (socket.connected) {\n    console.log('Manually disconnecting after 15 seconds...');\n    socket.disconnect();\n  }\n}, 15000);","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade both your `socket.io` server package and `socket.io-client` package to matching major versions. Refer to the official migration guides for specifics.","message":"Major 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).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For ESM, use `import { io } from 'socket.io-client';`. For CommonJS, use `const { io } = require('socket.io-client');`.","message":"Since `socket.io-client` v3, the main `io` function is a named export. This changes how it's imported in both ESM and CommonJS.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade `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.","message":"A 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.","severity":"security","affected_versions":"<4.2.6 (for v4), <3.4.4 (for v3), <3.3.5 (for v2)"},{"fix":"On your Socket.IO server, configure the `cors` option in `new Server(httpServer, { cors: { origin: \"*\", methods: [\"GET\", \"POST\"] } });` (or specify specific origins/methods).","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const { io } = require('socket.io-client');`. For ESM, ensure `import { io } from 'socket.io-client';`.","cause":"Attempting to import `io` as a default export in CommonJS or an incorrect named import.","error":"io is not a function"},{"fix":"Verify 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).","cause":"The Socket.IO server is either not running, not listening on the specified port/path, or the client/server major versions are mismatched.","error":"WebSocket connection to 'ws://localhost:3000/socket.io/?EIO=4&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 400"},{"fix":"Configure 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\"] } });`","cause":"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.","error":"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."}],"ecosystem":"npm"}