socket-io

Socket.IO Best Practices

Socket.IO v4.x is the bedrock for real-time communication in our applications. This guide establishes the definitive standards for its usage, focusing on reliability, performance, and maintainability.

1. Core Initialization & Security

Always initialize Socket.IO clients with explicit, secure, and efficient options.

✅ GOOD: Secure & Explicit Client Initialization

Use wss:// in production, enable CORS on the server for cross-origin clients, and avoid forceNew unless strictly necessary.

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

// For production, always use wss://
const socket = io("wss://api.yourdomain.com", {
  path: "/socket.io/", // Explicitly define path if customized on server
  transports: ["websocket", "polling"], // Prefer WebSocket, fallback to polling
  autoConnect: true, // Connect automatically
  auth: {
    token: "YOUR_AUTH_TOKEN", // Pass authentication data
  },
  query: {
    // Additional query parameters
    clientId: "unique-client-id",
  },
});

// Server-side (Node.js with Express)
// Ensure CORS is correctly configured for your client origin
const express = require("express");
const http = require("http");
const { Server } = require("socket.io");

const app = express();
const server = http.createServer(app);
const ioServer = new Server(server, {
  cors: {
    origin: "https://yourclientdomain.com", // Your client's domain
    methods: ["GET", "POST"],
    credentials: true,
  },
  path: "/socket.io/", // Match client path
});

ioServer.on("connection", (socket) => {
  // Access auth token: socket.handshake.auth.token
  // Access query params: socket.handshake.query.clientId
  console.log(`Client connected: ${socket.id}`);
});

❌ BAD: Insecure or Inefficient Initialization

Avoid http:// in production, implicit options, and unnecessary forceNew.

// client.js
// ❌ Insecure in production, relies on implicit defaults
const socket = io("http://localhost:3000");

// ❌ Creates a new underlying connection even if one exists for the same URL,
//    wasting resources unless specifically required for isolation.
const anotherSocket = io("https://api.yourdomain.com", { forceNew: true });