Socket.io mit Claude Code: Real-Time Kommunikation 2026
Real-Time-Features gehören zu den komplexesten Teilen moderner Webanwendungen: Race Conditions, Reconnect-Logik, Skalierung auf mehrere Server-Instanzen — Claude Code kennt die Fallstricke und implementiert Socket.io nach Production-Standard.
Socket.io vs. nativer WebSocket — wann lohnt sich der Overhead?
Nativer WebSocket ist eine Browser-API. Socket.io ist eine Abstraktionsschicht darüber — und dahinter steckt mehr als nur Syntax-Zucker. Bevor du dich für eine der beiden Optionen entscheidest, musst du die Unterschiede verstehen.
Socket.io — Vorteile
- Automatischer Reconnect mit Backoff
- Fallback auf HTTP Long Polling (ältere Firewalls)
- Rooms & Namespaces out-of-the-box
- Event-basiertes API (kein JSON.parse/stringify manuell)
- Acknowledgements (bestätigte Zustellung)
- Heartbeat / Ping-Pong eingebaut
- Redis Adapter für Multi-Server
Native WebSocket — wann besser
- Maximale Performance (kein Protocol-Overhead)
- Binary Protokolle (z. B. Gaming, Audio-Streams)
- Volle Kontrolle über das Framing
- Kein npm-Paket im Bundle
- Einfache 1:1-Verbindung ohne Rooms
- Microservices mit eigenem Protokoll
Entscheidungshilfe
Wann Socket.io wählen?
Chat-Apps, Collaboration Tools: Rooms, Presence, Typing-Indikatoren — alles eingebaut.
Dashboards & Live-Daten: Auto-Reconnect hält die Verbindung auch bei kurzem Netz-Dropout.
Multi-Server-Deployments: Redis Adapter synchronisiert Events über alle Instanzen.
Gaming / Audio-Streaming: Hier lieber nativen WebSocket oder WebRTC — Socket.io hat zu viel Overhead.
Claude Code Prompt-Tipp: Sag Claude Code nicht nur "Implementiere WebSocket". Gib den Use Case mit: "Chat-App mit Rooms, Presence-Status und Reconnect-Handling — welches Framework empfiehlst du und warum?" Claude Code erklärt Tradeoffs bevor es implementiert.
Server Setup mit TypeScript
Socket.io und TypeScript sind seit v4 erstklassig unterstützt. Das Server-Setup mit io.on, Rooms und Broadcast-Patterns sieht so aus:
Server
Express + Socket.io Server-Grundgerüst
# Claude Code Prompt:
# "Erstelle einen Socket.io v4 Server mit Express und TypeScript:
# - Connection-Handler mit User-Auth via JWT
# - Room beitreten/verlassen mit join/leave Events
# - Broadcast an Room-Mitglieder
# - Graceful Disconnect-Handling"
import express from 'express';
import { createServer } from 'http';
import { Server, Socket } from 'socket.io';
import jwt from 'jsonwebtoken';
const app = express();
const httpServer = createServer(app);
const io = new Server(httpServer, {
cors: {
origin: process.env.FRONTEND_URL,
credentials: true
},
// Ping-Timeout und Intervall tunen:
pingTimeout: 60000,
pingInterval: 25000
});
// Auth-Middleware: JWT aus handshake.auth prüfen
io.use(async (socket, next) => {
try {
const token = socket.handshake.auth?.token;
if (!token) return next(new Error('Authentication required'));
const payload = jwt.verify(token, process.env.JWT_SECRET!) as { sub: string };
socket.data.userId = payload.sub;
next();
} catch {
next(new Error('Invalid token'));
}
});
// Connection-Handler
io.on('connection', (socket: Socket) => {
const userId = socket.data.userId;
console.log(`User ${userId} verbunden (${socket.id})`);
// Room beitreten
socket.on('room:join', async (roomId: string) => {
await socket.join(roomId);
// Anderen im Room Bescheid geben
socket.to(roomId).emit('room:user_joined', { userId, roomId });
// Dem joinenden User aktuelle Room-Mitglieder schicken
const members = await getRoomMembers(io, roomId);
socket.emit('room:members', { roomId, members });
});
// Room verlassen
socket.on('room:leave', async (roomId: string) => {
await socket.leave(roomId);
socket.to(roomId).emit('room:user_left', { userId, roomId });
});
// Nachricht an Room senden
socket.on('message:send', (data: { roomId: string; text: string }) => {
const message = {
id: crypto.randomUUID(),
userId,
text: data.text,
timestamp: new Date().toISOString()
};
// io.to = alle in Room inkl. Sender | socket.to = alle außer Sender
io.to(data.roomId).emit('message:received', message);
});
// Disconnect aufräumen
socket.on('disconnect', (reason) => {
console.log(`User ${userId} getrennt: ${reason}`);
// Socket.io entfernt automatisch aus allen Rooms
});
});
// Helper: Alle User-IDs in einem Room ermitteln
async function getRoomMembers(io: Server, roomId: string) {
const sockets = await io.in(roomId).fetchSockets();
return sockets.map(s => s.data.userId);
}
httpServer.listen(3001, () => console.log('Socket.io Server auf Port 3001'));
io.to() vs socket.to():
io.to(roomId) sendet an alle im Room inklusive des sendenden Sockets. socket.to(roomId) sendet an alle außer dem Sender — für Chat-Apps meist das richtige Verhalten. Claude Code macht das automatisch richtig wenn du den Use Case beschreibst.
Type-Safe Events mit TypeScript Interfaces
Socket.io v4 unterstützt generische Typen für Events — einer der größten Produktivitäts-Gewinne wenn du mit Claude Code arbeitest. Einmal definiert, gibt es Autocomplete für alle Events auf Client und Server.
TypeScript
ServerToClientEvents & ClientToServerEvents
# Prompt für vollständige Typisierung:
# "Definiere TypeScript-Interfaces für alle Socket.io Events:
# Server→Client: message:received, room:members, user:online
# Client→Server: message:send, room:join, room:leave, typing:start
# Mit Acknowledgement-Typen für room:join"
// shared/socket-types.ts — wird von Server UND Client importiert
export interface Message {
id: string;
userId: string;
text: string;
timestamp: string;
roomId: string;
}
export interface RoomMember {
userId: string;
username: string;
avatar?: string;
online: boolean;
}
// Events die der Server an Clients sendet
export interface ServerToClientEvents {
'message:received': (message: Message) => void;
'message:deleted': (data: { messageId: string; roomId: string }) => void;
'room:members': (data: { roomId: string; members: RoomMember[] }) => void;
'room:user_joined': (data: { userId: string; roomId: string }) => void;
'room:user_left': (data: { userId: string; roomId: string }) => void;
'typing:indicator': (data: { userId: string; roomId: string; isTyping: boolean }) => void;
'user:online': (data: { userId: string; online: boolean }) => void;
'error': (data: { code: string; message: string }) => void;
}
// Events die der Client an den Server sendet
export interface ClientToServerEvents {
'message:send': (data: { roomId: string; text: string }) => void;
'message:delete': (messageId: string) => void;
// Acknowledgement: room:join liefert Antwort zurück
'room:join': (roomId: string, callback: (response: {
success: boolean;
members?: RoomMember[];
error?: string;
}) => void) => void;
'room:leave': (roomId: string) => void;
'typing:start': (roomId: string) => void;
'typing:stop': (roomId: string) => void;
}
// Interne Server-zu-Server Events (für Redis Adapter)
export interface InterServerEvents {
ping: () => void;
}
// Daten die auf jedem Socket gespeichert werden
export interface SocketData {
userId: string;
username: string;
}
// Server mit vollständiger Typisierung
import { Server } from 'socket.io';
import type { ServerToClientEvents, ClientToServerEvents, InterServerEvents, SocketData } from './shared/socket-types';
const io = new Server<
ClientToServerEvents,
ServerToClientEvents,
InterServerEvents,
SocketData
>(httpServer);
Shared Types = weniger Bugs: Lege die Interface-Datei in einem
shared/-Verzeichnis ab das sowohl Server als auch Client-Monorepo importieren können. Claude Code erkennt automatisch wenn ein Event-Name falsch geschrieben wurde — noch vor dem ersten Test.
React Hook für Socket.io
Eine der häufigsten Fehlerquellen: Socket-Verbindungen die nicht richtig aufgeräumt werden. Claude Code generiert einen soliden useSocket Hook mit korrektem Cleanup und Reconnect-Handling.
React
useSocket Hook mit Reconnect & Cleanup
# Prompt:
# "Erstelle einen React Hook useSocket für Socket.io v4:
# - Verbindung beim Mount aufbauen, beim Unmount trennen
# - Reconnect-Status im State (connected, reconnecting, error)
# - JWT-Token aus Auth-Context in handshake.auth übergeben
# - Typ-sicher mit unseren ServerToClientEvents"
import { useEffect, useRef, useState, useCallback } from 'react';
import { io, Socket } from 'socket.io-client';
import type { ServerToClientEvents, ClientToServerEvents } from '../shared/socket-types';
import { useAuth } from './useAuth';
type TypedSocket = Socket<ServerToClientEvents, ClientToServerEvents>;
export type ConnectionStatus = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'error';
export function useSocket() {
const { token } = useAuth();
const socketRef = useRef<TypedSocket | null>(null);
const [status, setStatus] = useState<ConnectionStatus>('disconnected');
const [error, setError] = useState<string | null>(null);
useEffect(() => {
if (!token) return;
setStatus('connecting');
const socket: TypedSocket = io(process.env.REACT_APP_SOCKET_URL!, {
auth: { token },
// Reconnect-Strategie:
reconnection: true,
reconnectionAttempts: 10,
reconnectionDelay: 1000,
reconnectionDelayMax: 30000, // max 30s zwischen Versuchen
randomizationFactor: 0.5 // Thundering Herd verhindern
});
socketRef.current = socket;
socket.on('connect', () => {
setStatus('connected');
setError(null);
});
socket.on('disconnect', (reason) => {
// Bei server-seitigem Disconnect nicht auto-reconnecten
if (reason === 'io server disconnect') {
socket.connect();
}
setStatus('disconnected');
});
socket.on('connect_error', (err) => {
setError(err.message);
setStatus('error');
});
socket.io.on('reconnect_attempt', () => setStatus('reconnecting'));
socket.io.on('reconnect', () => setStatus('connected'));
socket.io.on('reconnect_failed', () => setStatus('error'));
// Cleanup beim Unmount
return () => {
socket.removeAllListeners();
socket.disconnect();
socketRef.current = null;
};
}, [token]);
const joinRoom = useCallback((roomId: string) => {
return new Promise<{ members: RoomMember[] }>((resolve, reject) => {
socketRef.current?.emit('room:join', roomId, (response) => {
if (response.success) resolve({ members: response.members! });
else reject(new Error(response.error));
});
});
}, []);
return { socket: socketRef.current, status, error, joinRoom };
}
Wichtig — Stale Closure: Wenn du Event-Listener innerhalb von
useEffect registrierst, nutze immer useRef für den Socket — niemals direkt State. Claude Code erkennt dieses Pattern und warnt wenn Event-Handler stale closures erzeugen würden.
Chat-App Beispiel: Rooms, Private Nachrichten, Presence
Ein vollständiges Chat-Beispiel das Rooms, private 1:1-Nachrichten und Presence (Online-Status) kombiniert — die drei Bausteine fast jeder Real-Time-App.
Rooms
Private Msgs
Presence
Chat Room Component mit Typing-Indicator
# Prompt:
# "Chat-Room Komponente mit:
# - Nachrichtenliste (useReducer für State-Management)
# - Typing-Indicator mit Debounce (500ms)
# - Online-Status der Room-Mitglieder
# - Optimistic Updates (Nachricht sofort anzeigen, dann bestätigen)"
import { useEffect, useReducer, useCallback, useRef } from 'react';
import { useSocket } from '../hooks/useSocket';
import type { Message, RoomMember } from '../shared/socket-types';
type ChatState = {
messages: Message[];
members: RoomMember[];
typingUsers: Set<string>;
};
type ChatAction =
| { type: 'MESSAGE_RECEIVED'; payload: Message }
| { type: 'MEMBERS_UPDATED'; payload: RoomMember[] }
| { type: 'TYPING_START'; payload: string }
| { type: 'TYPING_STOP'; payload: string }
| { type: 'USER_ONLINE'; payload: { userId: string; online: boolean } };
function chatReducer(state: ChatState, action: ChatAction): ChatState {
switch (action.type) {
case 'MESSAGE_RECEIVED':
return { ...state, messages: [...state.messages, action.payload] };
case 'MEMBERS_UPDATED':
return { ...state, members: action.payload };
case 'TYPING_START': {
const newTyping = new Set(state.typingUsers);
newTyping.add(action.payload);
return { ...state, typingUsers: newTyping };
}
case 'TYPING_STOP': {
const newTyping = new Set(state.typingUsers);
newTyping.delete(action.payload);
return { ...state, typingUsers: newTyping };
}
case 'USER_ONLINE':
return {
...state,
members: state.members.map(m =>
m.userId === action.payload.userId
? { ...m, online: action.payload.online }
: m
)
};
default: return state;
}
}
export function ChatRoom({ roomId }: { roomId: string }) {
const { socket, status, joinRoom } = useSocket();
const [state, dispatch] = useReducer(chatReducer, {
messages: [], members: [], typingUsers: new Set()
});
const typingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
// Room beitreten und Event-Listener registrieren
useEffect(() => {
if (!socket || status !== 'connected') return;
joinRoom(roomId).then(({ members }) => {
dispatch({ type: 'MEMBERS_UPDATED', payload: members });
});
socket.on('message:received', (msg) =>
dispatch({ type: 'MESSAGE_RECEIVED', payload: msg })
);
socket.on('room:members', ({ members }) =>
dispatch({ type: 'MEMBERS_UPDATED', payload: members })
);
socket.on('typing:indicator', ({ userId, isTyping }) =>
dispatch({ type: isTyping ? 'TYPING_START' : 'TYPING_STOP', payload: userId })
);
socket.on('user:online', (data) =>
dispatch({ type: 'USER_ONLINE', payload: data })
);
return () => {
socket.off('message:received');
socket.off('room:members');
socket.off('typing:indicator');
socket.off('user:online');
socket.emit('room:leave', roomId);
};
}, [socket, status, roomId]);
// Typing-Indicator mit Debounce
const handleTyping = useCallback(() => {
socket?.emit('typing:start', roomId);
if (typingTimerRef.current) clearTimeout(typingTimerRef.current);
typingTimerRef.current = setTimeout(() => {
socket?.emit('typing:stop', roomId);
}, 500);
}, [socket, roomId]);
const sendMessage = useCallback((text: string) => {
socket?.emit('message:send', { roomId, text });
}, [socket, roomId]);
// ...JSX render
}
Private
Private 1:1-Nachrichten via User-Room
# Private Nachrichten ohne separaten "DM-Channel" im Server:
# Jeder User hat automatisch einen persönlichen Room mit seiner userId
// Server: Beim Connect in eigenen User-Room joinen
io.on('connection', (socket) => {
const userId = socket.data.userId;
// User-spezifischer Room = einfachstes Private-Messaging Pattern
socket.join(`user:${userId}`);
socket.on('message:private', ({ toUserId, text }) => {
const message = {
from: userId, to: toUserId,
text, timestamp: new Date().toISOString()
};
// An Empfänger senden
io.to(`user:${toUserId}`).emit('message:private_received', message);
// Auch Sender bekommt Kopie (für Multi-Device)
io.to(`user:${userId}`).emit('message:private_received', message);
});
});
Horizontales Scaling mit Redis Adapter
Sobald deine App auf mehr als eine Server-Instanz skaliert — Kubernetes, Load Balancer, mehrere VPS — gibt es ein kritisches Problem: Ein Socket auf Server A kann keine Events an Sockets auf Server B senden. Der Redis Adapter löst das.
Redis
Scaling
Redis Adapter Setup für Multi-Server
# Prompt:
# "Integriere socket.io-adapter/redis-streams-adapter für horizontales Scaling:
# - Redis-Verbindung mit ioredis
# - Adapter konfigurieren
# - Sticky Sessions im Load Balancer erklären"
import { createClient } from 'redis';
import { createAdapter } from '@socket.io/redis-streams-adapter';
import { Server } from 'socket.io';
async function bootstrap() {
// Redis-Clients: separate Instanzen für pub und sub empfohlen
const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();
await Promise.all([pubClient.connect(), subClient.connect()]);
const io = new Server(httpServer, {
adapter: createAdapter(pubClient, subClient),
// WICHTIG: Sticky Sessions für initiales Handshake
// Nach dem Upgrade läuft alles über Redis
});
// Ab jetzt funktioniert io.to() über alle Server-Instanzen
io.on('connection', (socket) => {
socket.on('message:send', ({ roomId, text }) => {
// Dieser Emit erreicht Sockets auf ALLEN Instanzen im Room
io.to(roomId).emit('message:received', { text });
});
});
}
bootstrap();
Load Balancer
Nginx Sticky Sessions für Socket.io
# Nginx upstream mit sticky sessions — PFLICHT für Socket.io:
# Ohne sticky sessions: WebSocket-Upgrade kann auf falschem Server landen
upstream socketio_backend {
# ip_hash = einfachstes Sticky-Session-Verfahren
ip_hash;
server backend-1:3001;
server backend-2:3001;
server backend-3:3001;
}
server {
location /socket.io/ {
proxy_pass http://socketio_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# Timeout erhöhen für Long-lived Connections
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}
Redis Streams vs. Redis Pub/Sub: Das neuere
@socket.io/redis-streams-adapter (auf Redis Streams basierend) ist gegenüber dem klassischen socket.io-redis bevorzugt — stabiler bei hoher Last und kein Message-Verlust bei kurzem Redis-Ausfall. Claude Code empfiehlt das automatisch wenn du nach "Socket.io Scaling" fragst.
Monitoring
Connection-Metriken im Production-Betrieb
# Wichtige Metriken die Claude Code automatisch integriert:
// Prometheus-Metriken für Socket.io
import { collectDefaultMetrics, Gauge, Counter } from 'prom-client';
const activeConnections = new Gauge({
name: 'socketio_connections_active',
help: 'Anzahl aktiver Socket.io Verbindungen'
});
const messagesTotal = new Counter({
name: 'socketio_messages_total',
help: 'Gesendete Nachrichten gesamt',
labelNames: ['room']
});
io.on('connection', (socket) => {
activeConnections.inc();
socket.on('message:send', ({ roomId }) => {
messagesTotal.labels(roomId).inc();
});
socket.on('disconnect', () => {
activeConnections.dec();
});
});
Real-Time Apps mit Claude Code entwickeln
Socket.io, TypeScript, Redis Adapter — Claude Code kennt alle Production-Patterns. Statt Stunden mit Debugging zu verbringen beschreibst du deinen Use Case und bekommst direkt lauffähigen, skalierbaren Code.
14 Tage kostenlos testen →Zusammenfassung: Socket.io Produktions-Checkliste
TypeScript-Interfaces:
ServerToClientEvents & ClientToServerEvents definiert — kein typobedingte Event-Namens-Fehler mehr.Auth-Middleware: JWT aus
handshake.auth validiert, User-Daten auf socket.data gespeichert.React Cleanup:
socket.removeAllListeners() + socket.disconnect() im useEffect-Cleanup.Reconnect-Strategie:
reconnectionDelayMax + randomizationFactor verhindert Thundering Herd bei Server-Restart.Redis Adapter:
@socket.io/redis-streams-adapter für Multi-Server — io.to(roomId) funktioniert über alle Instanzen.Sticky Sessions: Nginx
ip_hash stellt sicher dass der initiale Handshake immer denselben Server erreicht.Monitoring: Prometheus-Metriken für aktive Connections + Messages-Count pro Room.
Nicht vergessen:
socket.off() für jeden registrierten Listener im Cleanup — sonst Memory Leaks in langlebigen SPA-Sessions.Nächste Schritte
Du hast jetzt alle Bausteine für eine Production-ready Real-Time-App: Server-Setup mit TypeScript, Type-Safe Events, React Hooks, Chat-Patterns und horizontales Scaling mit Redis. Claude Code hilft dir dabei jeden dieser Schritte anzupassen — beschreibe deinen spezifischen Use Case und du bekommst sofort umsetzbare Implementierungen.
Verwandte Artikel: JWT Authentication, Caching-Strategien, AWS Lambda & Serverless.