ws-tap: watch live Socket.IO traffic in a second terminal (middleware + viewer, secrets redacted)

[Sahil-u07]

Hi all 👋 sharing a small dev tool in case it's useful to others here.

Whenever an event went missing in one of my Socket.IO apps, I ended up adding console.log to every handler, restarting, scrolling, and deleting it all again. ws-tap is a middleware that shows every event going in and out of your server, live, in a second terminal.

Setup

npm i -D @sahil-u07/ws-tap

const tap = require('@sahil-u07/ws-tap');
io.use(tap({ viewer: true }));

Then, in another terminal:

npx ws-tap

How it works

It's a plain io.use middleware. It hooks socket.onAny and socket.onAnyOutgoing on each socket, so it sees everything a socket receives and sends, including io.emit and room broadcasts, plus disconnects with the reason. Events go either to the console or, with viewer: true, as newline-delimited JSON over a localhost TCP socket to the viewer.

What you get

• Incoming / outgoing events, colour-coded, one colour per socket
• p pauses (events are held and printed on resume), f filters by event name or @socket-id
• password / token / secret / authorization keys are redacted at any depth, inside your app, before anything reaches the viewer
• Handles circular objects and Buffers, truncates huge payloads
• No-op when NODE_ENV=production unless you pass enabled: true
• Every hook is wrapped in try/catch, so it can't throw into your app
• If no viewer is running, events are dropped (no buffering) and the socket is unref'd, so it never keeps your process alive
• Zero dependencies, ~200 lines, MIT

Compatibility

Tested against socket.io 4.8.x (needs 4.5+ for onAnyOutgoing). Node 22.13+. Other namespaces: io.of('/admin').use(tap(...)).

Repo: https://github.com/Sahil-u07/ws-tap
npm: https://www.npmjs.com/package/@sahil-u07/ws-tap

Feedback I'd love

• Anything odd with adapters or namespaces? It watches each socket, so adapters shouldn't matter, but I'd like to hear if you hit a case.
• It's early (v0.3). Ack responses and room info are next on my list. What would you want it to show?