Building a Real-Time Backend with Socket.io

HTTP was built for documents. Chat is a conversation. Here's how to stop pretending one is the other.

Socket.io Node.js TypeScript WebSockets Backend Development Software Architecture

Loading articles...

Why HTTP Isn't Enough

Every web developer learns HTTP first. Request goes out, response comes back, connection closes. Clean. Stateless. Predictable.

Then someone asks you to build a chat app.

Suddenly that model collapses. Chat is fundamentally different from a page load — it's a persistent, bidirectional channel where either party can speak at any time. HTTP's request-response cycle forces you into awkward workarounds:

Short polling: The client hammers the server with GET /messages every second. Works, but wastes bandwidth and crushes server resources.
Long polling: The client makes a request and the server holds it open until there's new data. Better, but still stateful ugliness layered on a stateless protocol.
Server-Sent Events (SSE): Server can push to client, but not the reverse. Half a solution.

WebSockets solve this properly — a single TCP connection that stays open, allowing full-duplex communication. The client can send to the server and the server can push to the client independently, with near-zero overhead per message.

Socket.io is the library that makes WebSockets practical: it adds rooms, namespaces, automatic reconnection, fallback transports, and an event-based API that feels natural to JavaScript developers.

This article walks through building a complete real-time chat backend with Node.js and Socket.io — covering architecture, core events, rooms, authentication, and production concerns.

Project Setup

Start with a fresh Node.js project:

mkdir chat-backend && cd chat-backend
npm init -y
npm install express socket.io cors dotenv
npm install -D typescript @types/node @types/express ts-node nodemon

Initialize TypeScript:

npx tsc --init

Update tsconfig.json with sensible defaults:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Add scripts to package.json:

{
  "scripts": {
    "dev": "nodemon --exec ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

The Core Server

Create src/index.ts:

import express from "express";
import { createServer } from "http";
import { Server } from "socket.io";
import cors from "cors";
import dotenv from "dotenv";

dotenv.config();

const app = express();
const httpServer = createServer(app);

const io = new Server(httpServer, {
  cors: {
    origin: process.env.CLIENT_URL || "http://localhost:3000",
    methods: ["GET", "POST"],
    credentials: true,
  },
});

app.use(cors({ origin: process.env.CLIENT_URL, credentials: true }));
app.use(express.json());

// Health check
app.get("/health", (_req, res) => {
  res.json({ status: "ok", connections: io.engine.clientsCount });
});

const PORT = process.env.PORT || 4000;

httpServer.listen(PORT, () => {
  console.log(`🚀 Server running on port ${PORT}`);
});

export { io };

Two things to notice:

createServer(app) wraps Express inside a raw HTTP server. Socket.io attaches to the HTTP server, not to Express directly. This lets both share the same port.
The cors config on the Socket.io Server instance is separate from the Express CORS middleware — you need both.

Modeling the Domain

Before wiring up events, define the types. Create src/types.ts:

export interface User {
  id: string;
  username: string;
  avatar?: string;
}

export interface Message {
  id: string;
  roomId: string;
  author: User;
  content: string;
  timestamp: number;
  type: "text" | "system";
}

export interface Room {
  id: string;
  name: string;
  members: Map<string, User>;
  createdAt: number;
}

// Extend Socket.io's Socket type to carry user context
import { Socket } from "socket.io";

export interface AuthenticatedSocket extends Socket {
  user?: User;
}

Having types early prevents the classic Socket.io mistake: treating sockets as any-typed message buses and losing track of what's in each payload.

In-Memory State

For a production system you'd use Redis. For this walkthrough, in-memory maps are enough to understand the mechanics. Create src/store.ts:

import { Room, User } from "./types";

// roomId -> Room
export const rooms = new Map<string, Room>();

// socketId -> User
export const connectedUsers = new Map<string, User>();

export function getOrCreateRoom(roomId: string, name: string): Room {
  if (!rooms.has(roomId)) {
    rooms.set(roomId, {
      id: roomId,
      name,
      members: new Map(),
      createdAt: Date.now(),
    });
  }
  return rooms.get(roomId)!;
}

export function getRoomMembers(roomId: string): User[] {
  const room = rooms.get(roomId);
  if (!room) return [];
  return Array.from(room.members.values());
}

export function removeUserFromAllRooms(socketId: string): string[] {
  const affected: string[] = [];
  rooms.forEach((room, roomId) => {
    if (room.members.has(socketId)) {
      room.members.delete(socketId);
      affected.push(roomId);
    }
  });
  return affected;
}

Authentication Middleware

Socket.io has a middleware system that runs before a connection is established — perfect for token validation. Create src/middleware/auth.ts:

import { AuthenticatedSocket, User } from "../types";

// Stub: replace with real JWT verification
function verifyToken(token: string): User | null {
  if (!token || token === "invalid") return null;

  // In production: jwt.verify(token, process.env.JWT_SECRET)
  return {
    id: `user_${Math.random().toString(36).slice(2, 8)}`,
    username: token,
    avatar: `https://api.dicebear.com/7.x/avataaars/svg?seed=${token}`,
  };
}

export function authMiddleware(
  socket: AuthenticatedSocket,
  next: (err?: Error) => void
) {
  const token =
    socket.handshake.auth.token ||
    socket.handshake.headers["authorization"]?.replace("Bearer ", "");

  if (!token) {
    return next(new Error("Authentication required"));
  }

  const user = verifyToken(token);

  if (!user) {
    return next(new Error("Invalid token"));
  }

  socket.user = user;
  next();
}

import { authMiddleware } from "./middleware/auth";

io.use(authMiddleware);

Any socket that fails this middleware never reaches the connection handler — the client receives an error event with the message you passed to next(new Error(...)).

The Connection Handler

This is the heart of the application. Create src/handlers/connection.ts:

import { Server } from "socket.io";
import { v4 as uuidv4 } from "uuid";
import { AuthenticatedSocket, Message } from "../types";
import {
  connectedUsers,
  getOrCreateRoom,
  getRoomMembers,
  removeUserFromAllRooms,
  rooms,
} from "../store";

export function registerConnectionHandlers(io: Server) {
  io.on("connection", (socket: AuthenticatedSocket) => {
    const user = socket.user!;

    console.log(`✅ ${user.username} connected (${socket.id})`);
    connectedUsers.set(socket.id, user);

    // ── JOIN ROOM ────────────────────────────────────────────────
    socket.on(
      "room:join",
      (payload: { roomId: string; roomName: string }) => {
        const { roomId, roomName } = payload;
        const room = getOrCreateRoom(roomId, roomName);

        socket.join(roomId);
        room.members.set(socket.id, user);

        // Notify the joining user of current members
        socket.emit("room:joined", {
          room: { ...room, members: getRoomMembers(roomId) },
        });

        // System message to the room
        const systemMessage: Message = {
          id: uuidv4(),
          roomId,
          author: { id: "system", username: "System" },
          content: `${user.username} joined the room`,
          timestamp: Date.now(),
          type: "system",
        };

        socket.to(roomId).emit("message:received", systemMessage);
        io.to(roomId).emit("room:members", getRoomMembers(roomId));
      }
    );

    // ── LEAVE ROOM ───────────────────────────────────────────────
    socket.on("room:leave", (payload: { roomId: string }) => {
      const { roomId } = payload;
      const room = rooms.get(roomId);

      if (room) {
        room.members.delete(socket.id);
        socket.leave(roomId);

        const systemMessage: Message = {
          id: uuidv4(),
          roomId,
          author: { id: "system", username: "System" },
          content: `${user.username} left the room`,
          timestamp: Date.now(),
          type: "system",
        };

        io.to(roomId).emit("message:received", systemMessage);
        io.to(roomId).emit("room:members", getRoomMembers(roomId));
      }
    });

    // ── SEND MESSAGE ─────────────────────────────────────────────
    socket.on(
      "message:send",
      (payload: { roomId: string; content: string }) => {
        const { roomId, content } = payload;

        if (!content?.trim() || content.length > 2000) return;

        const room = rooms.get(roomId);
        if (!room || !room.members.has(socket.id)) {
          socket.emit("error", { message: "Not a member of this room" });
          return;
        }

        const message: Message = {
          id: uuidv4(),
          roomId,
          author: user,
          content: content.trim(),
          timestamp: Date.now(),
          type: "text",
        };

        // Broadcast to ALL members including sender
        io.to(roomId).emit("message:received", message);
      }
    );

    // ── TYPING INDICATORS ────────────────────────────────────────
    socket.on("typing:start", (payload: { roomId: string }) => {
      socket.to(payload.roomId).emit("typing:update", {
        userId: user.id,
        username: user.username,
        isTyping: true,
      });
    });

    socket.on("typing:stop", (payload: { roomId: string }) => {
      socket.to(payload.roomId).emit("typing:update", {
        userId: user.id,
        username: user.username,
        isTyping: false,
      });
    });

    // ── DISCONNECT ───────────────────────────────────────────────
    socket.on("disconnect", (reason) => {
      console.log(`❌ ${user.username} disconnected (${reason})`);
      connectedUsers.delete(socket.id);

      const affectedRooms = removeUserFromAllRooms(socket.id);

      affectedRooms.forEach((roomId) => {
        const systemMessage: Message = {
          id: uuidv4(),
          roomId,
          author: { id: "system", username: "System" },
          content: `${user.username} disconnected`,
          timestamp: Date.now(),
          type: "system",
        };

        io.to(roomId).emit("message:received", systemMessage);
        io.to(roomId).emit("room:members", getRoomMembers(roomId));
      });
    });
  });
}

Install uuid:

npm install uuid && npm install -D @types/uuid

import { registerConnectionHandlers } from "./handlers/connection";

registerConnectionHandlers(io);

Understanding the Emission Targets

The most common source of confusion in Socket.io is knowing who receives an event. Here's a definitive reference:

// Send to the sender only
socket.emit("event", data);

// Send to everyone in a room EXCEPT the sender
socket.to("roomId").emit("event", data);

// Send to EVERYONE in a room INCLUDING the sender
io.to("roomId").emit("event", data);

// Send to a specific socket by ID
io.to(socketId).emit("event", data);

// Send to everyone connected (all rooms, all sockets)
io.emit("event", data);

// Send to everyone EXCEPT the sender (global broadcast)
socket.broadcast.emit("event", data);

Getting this wrong is the number one bug in new Socket.io backends — a message sent with socket.to() when it should be io.to() silently drops the sender from the audience.

The Event Contract

A good Socket.io API has a documented event contract. Here's the contract for this chat backend:

Client → Server

Event	Payload	Description
`room:join`	`{ roomId, roomName }`	Join or create a room
`room:leave`	`{ roomId }`	Leave a room
`message:send`	`{ roomId, content }`	Send a message to a room
`typing:start`	`{ roomId }`	User started typing
`typing:stop`	`{ roomId }`	User stopped typing

Server → Client

Event	Payload	Description
`room:joined`	`{ room }`	Confirmation with room state
`room:members`	`User[]`	Updated member list
`message:received`	`Message`	New message in a room
`typing:update`	`{ userId, username, isTyping }`	Typing status changed
`error`	`{ message }`	Error from the server

Document this contract — ideally in a shared types package if your frontend is TypeScript. Both sides of the WebSocket should import from the same source of truth.

Typing Indicators Done Right

Naively, you'd emit typing:start on every keydown. This floods the server. The correct approach is debouncing — emit start when typing begins, and stop after a pause:

// Client-side debounce (shown for context)
let typingTimeout: ReturnType<typeof setTimeout>;

messageInput.addEventListener("input", () => {
  socket.emit("typing:start", { roomId: currentRoomId });

  clearTimeout(typingTimeout);
  typingTimeout = setTimeout(() => {
    socket.emit("typing:stop", { roomId: currentRoomId });
  }, 2000); // Stop signal after 2s of inactivity
});

On the server side, no changes needed — it's already handled statelessly by re-emitting the event to the room.

Namespaces: Organizing at Scale

If you're building multiple real-time features — chat, notifications, live cursors — don't dump everything into the default namespace (/). Socket.io namespaces act as independent channels:

// Default namespace (what we've built so far)
io.on("connection", handler);

// Separate namespace for notifications
const notificationsNsp = io.of("/notifications");
notificationsNsp.use(authMiddleware);
notificationsNsp.on("connection", (socket) => {
  // Notification-specific handlers
});

// Separate namespace for admin dashboard
const adminNsp = io.of("/admin");
adminNsp.use(adminAuthMiddleware);
adminNsp.on("connection", (socket) => {
  // Admin-only events
});

Clients connect to namespaces explicitly:

const chatSocket = io("http://localhost:4000");           // default /
const notifSocket = io("http://localhost:4000/notifications");

Each namespace has its own middleware chain, event handlers, and rooms — they don't bleed into each other.

Scaling with the Redis Adapter

An in-memory Socket.io server breaks the moment you deploy more than one instance. If Client A is connected to Instance 1 and Client B to Instance 2, io.to(roomId).emit() on Instance 1 will never reach Client B.

The fix is the Redis adapter, which uses Redis Pub/Sub to coordinate events across instances:

npm install @socket.io/redis-adapter ioredis

import { createAdapter } from "@socket.io/redis-adapter";
import { createClient } from "ioredis";

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

await Promise.all([pubClient.connect(), subClient.connect()]);

io.adapter(createAdapter(pubClient, subClient));

With this in place, all Socket.io instances share room state through Redis. You can horizontally scale behind a load balancer — with one requirement: the load balancer must use sticky sessions so that the WebSocket upgrade handshake and subsequent messages route to the same server instance.

Rate Limiting and Abuse Prevention

A public chat backend without rate limiting will be abused. Add per-socket throttling:

// src/middleware/rateLimit.ts
const MESSAGE_LIMIT = 10;  // max messages
const WINDOW_MS = 5000;    // per 5 seconds

const messageCounters = new Map<string, { count: number; resetAt: number }>();

export function checkRateLimit(socketId: string): boolean {
  const now = Date.now();
  const counter = messageCounters.get(socketId);

  if (!counter || now > counter.resetAt) {
    messageCounters.set(socketId, { count: 1, resetAt: now + WINDOW_MS });
    return true;
  }

  if (counter.count >= MESSAGE_LIMIT) return false;

  counter.count++;
  return true;
}

Use it in the message:send handler:

import { checkRateLimit } from "../middleware/rateLimit";

socket.on("message:send", (payload) => {
  if (!checkRateLimit(socket.id)) {
    socket.emit("error", { message: "Slow down — you're sending too fast." });
    return;
  }
  // ... rest of handler
});

Message Persistence

The in-memory store loses everything on restart. In production, persist messages to a database. Here's a minimal persistence layer using Prisma:

// src/db/messages.ts
import { PrismaClient } from "@prisma/client";
import { Message } from "../types";

const prisma = new PrismaClient();

export async function saveMessage(message: Message): Promise<void> {
  await prisma.message.create({
    data: {
      id: message.id,
      roomId: message.roomId,
      authorId: message.author.id,
      content: message.content,
      timestamp: new Date(message.timestamp),
      type: message.type,
    },
  });
}

export async function getRecentMessages(
  roomId: string,
  limit = 50
): Promise<Message[]> {
  const rows = await prisma.message.findMany({
    where: { roomId },
    orderBy: { timestamp: "desc" },
    take: limit,
    include: { author: true },
  });

  return rows.reverse().map((row) => ({
    id: row.id,
    roomId: row.roomId,
    author: { id: row.author.id, username: row.author.username },
    content: row.content,
    timestamp: row.timestamp.getTime(),
    type: row.type as "text" | "system",
  }));
}

Send history to the client when they join a room:

socket.on("room:join", async (payload) => {
  // ... join room logic ...

  // Send message history to the joining user only
  const history = await getRecentMessages(roomId, 50);
  socket.emit("room:history", history);
});

Testing the Backend

Test WebSocket events without a frontend using a quick client script:

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

const socket = io("http://localhost:4000", {
  auth: { token: "alice" },
});

socket.on("connect", () => {
  console.log("Connected:", socket.id);
  socket.emit("room:join", { roomId: "general", roomName: "General" });
});

socket.on("room:joined", (data) => {
  console.log("Joined room:", data);
  socket.emit("message:send", {
    roomId: "general",
    content: "Hello from the test client!",
  });
});

socket.on("message:received", (message) => {
  console.log("Message:", message);
});

socket.on("error", (err) => {
  console.error("Socket error:", err);
});

For automated testing, use socket.io-client inside Jest or Vitest with a real server instance spun up per test suite.

Production Checklist

Before shipping to production, verify these:

Sticky sessions on load balancer — required if running multiple instances.
Redis adapter — if running more than one server instance, period.
CORS locked to known origins — never origin: "*" in production.
Auth middleware on all namespaces — don't leave any namespace open.
Rate limiting on message events — per-socket, per-event-type throttle.
Input validation — trim and length-check every payload field.
Message persistence — in-memory stores disappear on restart/crash.
Graceful shutdown — call io.close() on SIGTERM.
Monitoring — track io.engine.clientsCount, reconnection rates, and event throughput.
TLS termination — run behind HTTPS/WSS. Never expose plain WS in production.

The Final File Structure

chat-backend/
├── src/
│   ├── handlers/
│   │   └── connection.ts      # All socket event handlers
│   ├── middleware/
│   │   ├── auth.ts            # Token verification
│   │   └── rateLimit.ts       # Per-socket throttling
│   ├── db/
│   │   └── messages.ts        # Persistence layer
│   ├── store.ts               # In-memory state
│   ├── types.ts               # Shared TypeScript types
│   └── index.ts               # Server entry point
├── test/
│   └── client.ts              # Manual test client
├── .env
├── package.json
└── tsconfig.json

Conclusion

Socket.io earns its popularity because it solves the right problems at the right layer of abstraction. Automatic reconnection, room management, and cross-transport fallbacks would each take significant effort to build on raw WebSockets — Socket.io makes them configuration.

The backend we've built here covers the full surface area of a real chat application: connection lifecycle, room membership, message broadcast, typing indicators, auth, rate limiting, and a clear path to persistence and horizontal scaling.

The patterns here — typed events, middleware auth, structured error responses, Redis for scale — aren't Socket.io-specific tricks. They're the engineering fundamentals that separate a weekend project from something you can actually trust in production.

Building a Real-Time Backend with Socket.io

Building a Real-Time Backend with Socket.io

Why HTTP Isn't Enough

Project Setup

The Core Server

Modeling the Domain

In-Memory State

Authentication Middleware

The Connection Handler

Understanding the Emission Targets

The Event Contract

Client → Server

Server → Client

Typing Indicators Done Right

Namespaces: Organizing at Scale

Scaling with the Redis Adapter

Rate Limiting and Abuse Prevention

Message Persistence

Testing the Backend

Production Checklist

The Final File Structure

Conclusion

InstaDoodle - AI Video Creator

related articles

What Is Model Context Protocol (MCP)?

TypeScript Utility Types You Should Use Every Day

Do We Still Need Tailwind CSS in 2026?