# Socket.IO — Bidirectional Realtime Event-Based Communication

> Socket.IO is a library that enables low-latency, bidirectional, event-based communication between a client and server. Built on WebSocket with fallbacks, automatic reconnection, room-based broadcast, and first-class Node.js support.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

Server (Node.js):
```bash
npm i socket.io
```

```ts
import { Server } from "socket.io";

const io = new Server(3000, { cors: { origin: "*" } });

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

  socket.on("message", (msg) => {
    io.emit("message", { user: socket.id, text: msg });
  });

  socket.on("join", (room) => {
    socket.join(room);
    io.to(room).emit("joined", socket.id);
  });
});
```

Client:
```bash
npm i socket.io-client
```

```ts
import { io } from "socket.io-client";

const socket = io("http://localhost:3000");
socket.on("message", (m) => console.log(m));
socket.emit("message", "Hello!");
```

## Intro

Socket.IO enables low-latency, bidirectional, event-based communication between client and server. Built on top of WebSocket with automatic fallback to HTTP long-polling for legacy environments. Features that raw WebSocket lacks: automatic reconnection, rooms/namespaces, broadcast, acknowledgments.

- **Repo**: https://github.com/socketio/socket.io
- **Stars**: 63K+
- **Language**: TypeScript
- **License**: MIT

## What Socket.IO Does

- **Events** — emit/on with any JSON payload
- **Acknowledgments** — callback-style confirmations
- **Rooms** — group sockets for targeted broadcasts
- **Namespaces** — logical channels over same connection
- **Auto-reconnect** — exponential backoff
- **Binary data** — Buffers/Blobs supported
- **Horizontal scaling** — Redis adapter for multi-node
- **Middleware** — auth, logging, rate limiting

## Architecture

The Engine.IO layer handles transport (WebSocket preferred, polling fallback, upgrade mechanism). Socket.IO adds protocol features (rooms, acks, binary, namespaces). Multi-server deploys use a Redis (or other) adapter to broadcast across nodes.

## Self-Hosting

```bash
# Standalone Node server
node server.js

# With Express
import express from "express";
import { Server } from "socket.io";
import http from "http";

const app = express();
const httpServer = http.createServer(app);
const io = new Server(httpServer);
httpServer.listen(3000);
```

## Key Features

- WebSocket + HTTP long-polling fallback
- Automatic reconnection
- Rooms and namespaces
- Acknowledgments (callback-style)
- Binary data support
- Horizontal scaling via adapters
- Middleware for auth
- Admin UI dashboard
- Multiple language clients (JS, Python, Java, Swift, Kotlin, C++)

## Comparison

| Library | Transport | Fallback | Rooms | Scaling |
|---|---|---|---|---|
| Socket.IO | WebSocket + HTTP | Yes | Built-in | Redis adapter |
| ws | WebSocket | No | DIY | DIY |
| SockJS | WebSocket + 8 fallbacks | Yes | No | DIY |
| Centrifugo | WebSocket | No | Built-in | Built-in |
| Ably/Pusher | WebSocket | Yes | Built-in | Managed SaaS |

## FAQ

**Q: How does it compare to native WebSocket?**
A: Native WebSocket is lighter, but you have to implement reconnection, heartbeats, and rooms yourself. Socket.IO provides all that out of the box.

**Q: How do I scale horizontally?**
A: Use `@socket.io/redis-adapter`. Multiple Node processes share broadcasts through Redis pub/sub.

**Q: Are protocols compatible across versions?**
A: Client and server versions must match (a v4 client can't connect to a v2 server). There's an official version compatibility table.

## Sources & Credits

- Docs: https://socket.io/docs
- GitHub: https://github.com/socketio/socket.io
- License: MIT

---
Source: https://tokrepo.com/en/workflows/socket-io-bidirectional-realtime-event-based-communication-b3e554ce
Author: AI Open Source