🔔 Real-time Notifications

Why Notifications Matter

For years, staying up to date meant hitting refresh. The old request/response cycle forced users to pull for news, which is a poor experience on three counts: users don't know when something changed, frequent polling wastes bandwidth and server cycles, and any update is stale by up to a full poll interval.

Real-time notifications flip this to a push model. The server pushes the moment an event happens, so the interface feels responsive and alive. You've already built the transport — Socket.IO — in the previous two lessons. Now we design the system that uses it well.

The Notification Flow

A notification isn't just an emit — it's a small pipeline. Something happens in your backend (an order ships, a comment is posted). A notification service decides who should hear about it and how, then routes it through Socket.IO to the right sockets. Seeing the whole path first makes the code that follows obvious.

The crucial insight is the mapping problem. Your app thinks in user ids ("notify user 42"), but Socket.IO thinks in socket ids — and one user may have several sockets open at once (laptop, phone, a second tab). The notification service's main job is to bridge that gap: given a user id, find all of that user's live sockets.

A Server-Side Notification Service

Let's build a small class that owns the user-to-socket mapping and exposes clean methods to notify a user, a room, or everyone. A tidy Socket.IO trick: have each socket join a room named after its user id on connect. Then "notify user 42" is simply "emit to room user:42" — and Socket.IO handles the multiple-devices problem for you, even across servers with the Redis adapter.

// notification-service.js
class NotificationService {
  constructor(io) {
    this.io = io;
  }

  // Build a consistent per-user room name
  userRoom(userId) {
    return `user:${userId}`;
  }

  // Send to every device of one user
  sendToUser(userId, type, data) {
    this.io.to(this.userRoom(userId)).emit('notification', {
      type,
      data,
      at: new Date().toISOString(),
    });
  }

  // Send to a named group (e.g. 'delivery-team')
  sendToRoom(room, type, data) {
    this.io.to(room).emit('notification', {
      type,
      data,
      at: new Date().toISOString(),
    });
  }

  // Send to everyone connected
  broadcast(type, data) {
    this.io.emit('notification', {
      type,
      data,
      at: new Date().toISOString(),
    });
  }
}

module.exports = NotificationService;

Notice every notification has the same envelope: a type (so the client knows how to render it), a data payload, and a timestamp. A consistent shape keeps the client simple — it routes on type and never has to guess.

Triggering from REST & Sockets

Notifications rarely originate from the socket itself. More often, some other part of your system — an order processor, a payment webhook, an admin action — needs to fire one. So expose the service through both an HTTP route (for backend-to-backend triggers) and the normal socket lifecycle.

// server.js
const express = require('express');
const http = require('http');
const { Server } = require('socket.io');
const NotificationService = require('./notification-service');

const app = express();
app.use(express.json());
const server = http.createServer(app);
const io = new Server(server);
const notifications = new NotificationService(io);

// --- Socket lifecycle: authenticate, then join the user's room ---
io.use((socket, next) => {
  const userId = verifyToken(socket.handshake.auth.token); // your auth
  if (!userId) return next(new Error('Unauthorized'));
  socket.data.userId = userId;
  next();
});

io.on('connection', (socket) => {
  const { userId } = socket.data;
  socket.join(`user:${userId}`);        // <-- the key line
  socket.emit('ready', { userId });
});

// --- REST trigger: any backend service can POST to notify a user ---
app.post('/api/notify/user/:userId', (req, res) => {
  const { type, data } = req.body;
  notifications.sendToUser(req.params.userId, type, data);
  res.json({ ok: true });
});

Now a real business event — say, an order status change — becomes a couple of readable lines:

// Somewhere in your order-processing code
orderEvents.on('status-change', (order) => {
  notifications.sendToUser(order.userId, 'order-update', {
    orderId: order.id,
    status: order.status,
    message: statusMessage(order.status),
  });

  // Deliveries also alert a shared team room
  if (order.status === 'out-for-delivery') {
    notifications.sendToRoom('delivery-team', 'new-delivery', {
      orderId: order.id,
      address: order.shippingAddress,
    });
  }
});

function statusMessage(status) {
  const messages = {
    processing: 'Your order is being processed.',
    shipped: 'Good news — your order has shipped!',
    'out-for-delivery': 'Your order is out for delivery.',
    delivered: 'Delivered. Enjoy!',
  };
  return messages[status] ?? `Order status: ${status}`;
}

The Toast UI

On the client, a notification should be noticeable but not intrusive — the classic "toast" that slides in, lingers a few seconds, and slides away. We'll build a small, dependency-free toast manager and wire it to the incoming notification event.

Receiving and routing notifications

// notification-client.js
const socket = io({ auth: { token: localStorage.getItem('jwt') } });

socket.on('notification', (note) => {
  // Route on the type field we standardized on the server
  switch (note.type) {
    case 'order-update':
      toast.info(`Order #${note.data.orderId}`, note.data.message);
      break;
    case 'message':
      toast.info(`New message from ${note.data.sender}`, note.data.preview);
      break;
    case 'friend-request':
      toast.success('Friend request', `${note.data.name} wants to connect`);
      break;
    default:
      toast.info('Notification', JSON.stringify(note.data));
  }
});

A minimal toast manager

The manager creates a fixed container once, then appends a toast element per notification and removes it after a timeout. Crucially, it builds nodes with textContent — never innerHTML with raw data — so a malicious message can't inject script.

class ToastManager {
  constructor() {
    this.container = document.createElement('div');
    this.container.id = 'toast-container';
    this.container.setAttribute('role', 'status');       // announced by
    this.container.setAttribute('aria-live', 'polite');  // screen readers
    document.body.appendChild(this.container);
  }

  show(title, message, type = 'info', duration = 5000) {
    const el = document.createElement('div');
    el.className = `toast toast-${type}`;

    const h = document.createElement('h4');
    h.textContent = title;        // textContent = safe against XSS
    const p = document.createElement('p');
    p.textContent = message;
    el.append(h, p);

    this.container.appendChild(el);
    setTimeout(() => this.dismiss(el), duration);
    return el;
  }

  dismiss(el) {
    el.classList.add('toast-hiding');
    el.addEventListener('transitionend', () => el.remove(), { once: true });
  }

  info(t, m)    { return this.show(t, m, 'info'); }
  success(t, m) { return this.show(t, m, 'success'); }
  error(t, m)   { return this.show(t, m, 'error'); }
}

const toast = new ToastManager();

Offline Delivery & Preferences

Two problems separate a toy demo from a real system. First, what if the user is offline when the event fires? An emit to a room with no sockets simply vanishes. Second, users want control — they don't all want every alert at every hour.

Persist, then deliver on reconnect

The fix for offline delivery: always store the notification in a database, then try to deliver it live. When a user reconnects, replay anything they missed.

class DurableNotificationService extends NotificationService {
  constructor(io, db) {
    super(io);
    this.db = db;
  }

  async sendToUser(userId, type, data) {
    // 1. Persist first, so nothing is ever lost
    const record = await this.db.notifications.insert({
      userId, type, data, delivered: false, read: false, createdAt: new Date(),
    });
    // 2. Then attempt live delivery
    super.sendToUser(userId, type, data);
    return record;
  }

  // Called when a user reconnects
  async replayUndelivered(userId, socket) {
    const missed = await this.db.notifications.find({ userId, delivered: false });
    if (missed.length) {
      socket.emit('notification-sync', missed);
      await this.db.notifications.markDelivered(missed.map((n) => n.id));
    }
  }
}

// On connect, catch the user up
io.on('connection', async (socket) => {
  const { userId } = socket.data;
  socket.join(`user:${userId}`);
  await notifications.replayUndelivered(userId, socket);
});

Respect user preferences

Before sending, check whether the user actually wants this. A preferences check gates every send — including a "do not disturb" quiet-hours window.

async function shouldSend(db, userId, type) {
  const prefs = await db.preferences.findOne({ userId });
  if (!prefs) return true;                       // default: send

  if (prefs.channels?.[type] === false) return false; // muted this type

  // Quiet hours (stored as minutes-since-midnight, user's timezone)
  if (prefs.quietHours?.enabled) {
    const now = minutesSinceMidnight(prefs.timezone);
    const { start, end } = prefs.quietHours;
    const inWindow = start < end
      ? now >= start && now < end          // same-day window
      : now >= start || now < end;         // overnight window
    if (inWindow) return false;
  }
  return true;
}

Practice & Quiz

sendToUser(userId, type, data) {
  this.io.to(`user:${userId}`).emit('notification', {
    type,
    data,
    at: new Date().toISOString(),
  });
}

function toast(title, message) {
  const el = document.createElement('div');
  el.className = 'toast';

  const h = document.createElement('h4');
  h.textContent = title;    // safe

  const p = document.createElement('p');
  p.textContent = message;  // safe

  el.append(h, p);
  document.getElementById('toast-container').appendChild(el);
  setTimeout(() => el.remove(), 5000);
}

Best Practices & Pitfalls

✅ Do

• Give every notification a consistent { type, data, timestamp } envelope
• Route to users via a per-user room so all their devices are covered
• Persist notifications, then deliver — so offline users never miss anything
• Check user preferences and quiet hours before sending
• Render text with textContent and place toasts in an aria-live region
• Throttle or group bursts so you don't bury the user in toasts

❌ Don't

• Assume an emit reached anyone — it silently vanishes if no socket is listening
• Inject notification data with innerHTML — that's a direct XSS vector
• Convey critical, must-see information through a toast that auto-dismisses
• Send to a single socket id when the user might be on several devices
• Ignore preferences — unwanted notifications train users to disable them entirely

Summary

📚 Additional Resources

• Socket.IO — Rooms (per-user targeting)
• MDN — The Push API
• MDN — The Notifications API
• MDN — The ARIA status role (live regions)

🚀 What's Next?

You've completed the real-time features track — transport, library, and a full notification system. Next we shift to another everyday full-stack challenge: getting large files from the browser to the server efficiently, in File Upload Strategies.