Setting Up Socket.io with Express

Socket.io attaches to the same HTTP server that Express already uses — they share port 5000 in development without any conflict. The Socket.io server wraps the HTTP server, intercepts WebSocket upgrade requests, and handles socket lifecycle events alongside Express’s normal route handling. In this lesson you will install Socket.io, attach it to the Express HTTP server, configure CORS for the socket connection, emit your first test events, and verify the real-time channel is working before adding any application-specific logic.

Installation #

cd server
npm install socket.io

cd ../client
npm install socket.io-client

Attaching Socket.io to Express #

// server/index.js — modified to support Socket.io
require('dotenv').config();

const express    = require('express');
const http       = require('http');    // ← needed to share server with Socket.io
const { Server } = require('socket.io');
const cors       = require('cors');
const connectDB  = require('./src/config/db');

const app    = express();
const server = http.createServer(app); // wrap Express app in HTTP server

// ── Socket.io attached to the same HTTP server ────────────────────────────────
const io = new Server(server, {
  cors: {
    origin:      process.env.CLIENT_URL || 'http://localhost:5173',
    methods:     ['GET', 'POST'],
    credentials: true,
  },
  pingTimeout:  60000, // disconnect after 60s without ping
  pingInterval: 25000, // ping every 25s to keep connection alive
});

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

// ── Express routes ─────────────────────────────────────────────────────────────
app.use('/api/auth',  require('./src/routes/auth'));
app.use('/api/posts', require('./src/routes/posts'));

// ── Socket.io connection handler ─────────────────────────────────────────────
io.on('connection', (socket) => {
  console.log(`Socket connected: ${socket.id}`);

  socket.on('disconnect', (reason) => {
    console.log(`Socket disconnected: ${socket.id} — ${reason}`);
  });

  socket.on('error', (err) => {
    console.error(`Socket error on ${socket.id}:`, err.message);
  });
});

// ── Start server ───────────────────────────────────────────────────────────────
const PORT = process.env.PORT || 5000;
const start = async () => {
  await connectDB();
  server.listen(PORT, () => console.log(`Server + Socket.io → http://localhost:${PORT}`));
};

start().catch(err => { console.error(err); process.exit(1); });

// ── Export io for use in route handlers ───────────────────────────────────────
module.exports = { app, io };

Verifying the Connection with a Browser Test #

// Quick browser console test — paste in DevTools console
// (while Socket.io client script is loaded or from the React app)

const socket = io('http://localhost:5000');

socket.on('connect',    ()    => console.log('Connected! ID:', socket.id));
socket.on('disconnect', ()    => console.log('Disconnected'));
socket.on('error',      (err) => console.error('Socket error:', err));

// Emit a test event
socket.emit('ping', { message: 'hello from browser' });

// Server console should log: Socket connected: abc123xyz

Accessing io in Controllers #

// server/src/config/socket.js — central socket access
let io;

const initSocket = (serverIo) => {
  io = serverIo;
};

const getIO = () => {
  if (!io) throw new Error('Socket.io not initialised');
  return io;
};

module.exports = { initSocket, getIO };

// server/index.js
const { initSocket } = require('./src/config/socket');
const socketIo = new Server(server, { cors: { ... } });
initSocket(socketIo); // store reference

// server/src/controllers/commentController.js
const { getIO } = require('../config/socket');

const createComment = asyncHandler(async (req, res) => {
  const comment = await Comment.create({ ... });

  // Emit to all clients viewing this post
  getIO()
    .to(`post:${req.params.postId}`)
    .emit('new-comment', comment);

  res.status(201).json({ success: true, data: comment });
});

Socket.io Server-Side API — Key Methods #

Common Mistakes #

Mistake 1 — Calling app.listen() instead of server.listen() #

❌ Wrong — Socket.io attached to the HTTP server but Express listens separately:

const server = http.createServer(app);
const io     = new Server(server, { ... });
app.listen(5000); // wrong! Socket.io is on server, not app

✅ Correct — listen on the HTTP server:

server.listen(5000); // ✓ both Express and Socket.io share port 5000

Mistake 2 — Missing Socket.io CORS configuration #

❌ Wrong — Express CORS configured but Socket.io CORS not set:

app.use(cors({ origin: 'http://localhost:5173' })); // Express only
const io = new Server(server); // no Socket.io CORS → browser blocked!

✅ Correct — configure CORS on the Socket.io server too:

const io = new Server(server, {
  cors: { origin: 'http://localhost:5173', credentials: true },
}); // ✓

Mistake 3 — Using io.emit() for post-specific events #

❌ Wrong — broadcasting a comment to ALL connected clients:

io.emit('new-comment', comment); // all 1000 connected users get this!

✅ Correct — emit only to the relevant room:

io.to(`post:${postId}`).emit('new-comment', comment); // ✓ only post viewers

Quick Reference #