Socket IO on medusa JS

[Gustavitory]

Hey everyone! 👋 Wanted to share a Socket.IO integration for Medusa v2 in case it helps anyone here.

TL;DR: I needed to attach a Socket.IO server to the same HTTP server Medusa creates internally (shared port, CORS, origin), but Medusa doesn't expose that http.Server instance anywhere — loaders only receive expressApp, and the server is created internally inside start.ts.

The only user-controlled hook that runs before http.createServer(...) is the register() function from instrumentation.ts (the same one used for OpenTelemetry). So I monkey-patch http.createServer from there: capture the first server Medusa creates, attach io to it, then restore createServer to the original. Fully working in dev (medusa develop with HMR) and prod, with bearer-JWT auth per actor namespace (/admin, /customer, /employee, /partner, plus a custom /shopper in our case) reusing getAuthContextFromJwtToken from @medusajs/framework/http.

I already raised this with the team and there might be a first-class hook coming, but in the meantime this is the cleanest approach I found. Patch file 👇

// instrumentation.ts (project root)
import http from "http";
import { Server as IOServer, type ServerOptions } from "socket.io";

declare global {
  // eslint-disable-next-line no-var
  var __medusaIo: IOServer | undefined;
  // eslint-disable-next-line no-var
  var __medusaIoPatched: boolean | undefined;
}

function parseOrigins(value: string | undefined): string[] | boolean {
  if (!value || value.trim() === "" || value.trim() === "*") return true;
  return value.split(",").map((s) => s.trim()).filter(Boolean);
}

const log = (msg: string, ...rest: unknown[]) =>
  console.log(`[socket.io] ${msg}`, ...rest);

export function register() {
  if (process.env.MEDUSA_WORKER_MODE === "worker") {
    log("worker mode: skip init");
    return;
  }
  if (globalThis.__medusaIoPatched) {
    log("already patched, skip");
    return;
  }
  globalThis.__medusaIoPatched = true;

  log("patching http.createServer…");
  const original = http.createServer.bind(http);

  http.createServer = function patchedCreateServer(...args: unknown[]) {
    const server = (original as any)(...args) as http.Server;
    log("http.Server captured");

    try {
      const path = process.env.SOCKET_IO_PATH || "/socket.io";
      const corsOrigin = parseOrigins(process.env.SOCKET_IO_CORS_ORIGIN);
      const options: Partial<ServerOptions> = {
        path,
        cors: { origin: corsOrigin, credentials: true },
      };

      const io = new IOServer(server, options);
      globalThis.__medusaIo = io;

      log(`initialized · path=${path}`);

      const shutdown = () => {
        log("closing io…");
        try { io.close(); } catch { /* noop */ }
      };
      process.once("SIGTERM", shutdown);
      process.once("SIGINT", shutdown);
    } catch (err) {
      console.error("[socket.io] init failed:", err);
    } finally {
      http.createServer = original; // restore — only patch the first call
    }

    return server;
  };
}

A custom Medusa module then runs as a regular module loader, picks up globalThis.__medusaIo, and registers per-actor namespaces with bearer-JWT auth. Happy to share that part too if anyone wants it. Feedback / better ideas welcome! 🙏

[Gustavitory]

#17783