typescript
// In your gateway...
async handleConnection(client: Socket) {
  const userId = client.handshake.auth.userId;
  await this.redis.set(`presence:${userId}`, '1', 'EX', 30);
  this.server.emit('user:online', { userId });
}

async handleDisconnect(client: Socket) {
  const userId = client.handshake.auth.userId;
  await this.redis.del(`presence:${userId}`);
  this.server.emit('user:offline', { userId });
}
And then you realize: what about users with multiple tabs open? What about ungraceful
disconnects that never fire the disconnect event? What about querying who's online in a
specific room? What about running this across 3 horizontally-scaled pods?

I've written this code — or a more complex version of it — on every real-time project
I've worked on for the past 5 years. Last week I searched npm for a dedicated NestJS
package that handled all of this. Nothing existed.

So I built it.

Introducing nestjs-socket-presence
A drop-in NestJS module that gives you complete, production-ready user presence tracking
via Socket.IO and Redis. Zero boilerplate. Works across multiple pods.


npm install nestjs-socket-presence ioredis
The problems it solves
Before I show the API, let me explain why naive presence tracking breaks in production.

Problem 1: The multiple tabs problem
A user opens your app in 3 browser tabs. Each tab opens a socket. They close tab 1.
Your naive implementation fires handleDisconnect and marks them offline — but they're
still connected via tabs 2 and 3.

nestjs-socket-presence tracks a set of socket IDs per user. The user only goes
offline when their last socket disconnects.

Problem 2: The ghost user problem
A user's laptop battery dies. No disconnect event fires. They're forever "online" in Redis.

nestjs-socket-presence uses Redis TTL expiry on every key. If the client doesn't send
a heartbeat within ttl seconds, they automatically go offline. No ghost users.

Problem 3: The multi-instance problem
You scale your NestJS app to 3 pods behind a load balancer. User A connects to Pod 1,
User B connects to Pod 3. Pod 1 has no idea User B exists.

nestjs-socket-presence stores all state in Redis — shared across every pod.
Presence is global, not local to a single process.

Problem 4: The room presence problem
You want to know: "which support agents are currently available in room support-tier-1?"
That's not just online/offline — it's presence scoped to a context.

nestjs-socket-presence has first-class room presence support.

Usage
1. Register the module

// app.module.ts
import { PresenceModule } from 'nestjs-socket-presence';

@Module({
  imports: [
    PresenceModule.register({
      redis: { host: 'localhost', port: 6379 },
      ttl: 30, // seconds — users go offline after 30s without heartbeat
    }),
  ],
})
export class AppModule {}
Works async too, for ConfigService:


PresenceModule.registerAsync({
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    redis: { url: config.get('REDIS_URL') },
    ttl: 30,
  }),
  inject: [ConfigService],
})
2. Connect from the client

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000', {
  auth: { userId: 'user-123' }, // userId in handshake → auto presence on connect
});
That's it. The user is tracked as online. On disconnect they go offline automatically.
The built-in PresenceGateway handles the entire lifecycle.

3. Keep presence alive (heartbeat)

// Client — call every ttl/2 seconds
setInterval(() => {
  socket.emit('presence:heartbeat', { userId: 'user-123' });
}, 15_000);
4. Query presence anywhere in your app

import { PresenceService } from 'nestjs-socket-presence';

@Injectable()
export class ChatService {
  constructor(private readonly presence: PresenceService) {}

  // Is a specific user online?
  async isAgentAvailable(agentId: string) {
    return this.presence.isOnline(agentId);
  }

  // Full presence details for a user
  async getUserStatus(userId: string) {
    return this.presence.getUserPresence(userId);
    // → { userId, online, socketIds, lastSeen, metadata? }
  }

  // Check hundreds of users at once — one Redis round-trip
  async getTeamStatus(userIds: string[]) {
    return this.presence.getBulkPresence(userIds);
    // → Map<string, boolean>
  }

  // Who's in a specific room right now?
  async getSupportRoomStatus(room: string) {
    return this.presence.getRoomPresence(room);
    // → { room, users: UserPresence[], onlineCount }
  }
}
5. Room presence (optional)

// Client joins a presence-tracked room
socket.emit('presence:room:join', { userId: 'user-123', room: 'support-tier-1' });

// Server pushes to the room when someone joins/leaves
socket.on('presence:room:join', ({ userId, room }) => {
  console.log(`${userId} joined ${room}`);
});

// Query who's currently in the room
const roomStatus = await this.presence.getRoomPresence('support-tier-1');
console.log(`${roomStatus.onlineCount} agents available`);
Real-world use cases
Customer support platforms — show which agents are available before routing a
customer's chat. If an agent closes their laptop, they go offline automatically after
the TTL expires.

Collaborative editors — "3 people are viewing this document right now." Track
presence per document room.

Live dashboards — know which operators are actively monitoring. Show a live
"who's watching" indicator.

Gaming lobbies — track which players are ready. Clean up presence automatically
when a player disconnects.

How the Redis keys are structured

presence:user:{userId}          HASH   → { userId, online, lastSeen, metadata? }
presence:user:{userId}:sockets  SET    → { socketId1, socketId2, ... }
presence:socket:{socketId}      STRING → userId
presence:room:{room}            SET    → { userId1, userId2, ... }
The socket→userId mapping is what enables clean multi-tab handling: on disconnect,
we look up which user owned that socket, remove it from their socket set, and only
mark them offline if the set is now empty.

Attach metadata to presence
Pass arbitrary metadata when a user comes online — useful for role, region, or
device type:


// Call from your own gateway or auth interceptor
await this.presenceService.setOnline(userId, socket.id, {
  role: 'senior-agent',
  region: 'us-east',
  department: 'billing',
});

// Read it back in room presence queries
const room = await this.presenceService.getRoomPresence('support-tier-1');
const billingAgents = room.users.filter(u => u.metadata?.department === 'billing');
What's next
This is v1.0.0. Things I'm planning for upcoming releases:

Presence events as NestJS events — emit via EventEmitter2 so you can hook into online/offline without touching the gateway
Presence guards — @RequireOnline() decorator for gateway message handlers
Analytics hook — optional callback on every presence change for logging/metrics
If any of these would solve a problem you have right now, open an issue or PR on GitHub —
I'd love to build it with the community.

Links
npm: https://www.npmjs.com/package/nestjs-socket-presence
GitHub: https://github.com/SaifuddinTipu/nestjs-socket-presence
22 unit tests. Full TypeScript with declaration files. MIT license.

If this saves you from copy-pasting presence code into your next NestJS project, drop
a ⭐ on GitHub — it helps others discover it.