Real-Time Notifications (WebSocket)

A scalable, developer-ready WebSocket notification system for Express with optional email and queue-based delivery.

websocketnotificationsrealtimeexpresssocketioemailqueue

v2.0.0bundles

Overview

A powerful, real-time notification system using WebSocket (Socket.IO) for instant delivery across clients. Supports persistent storage (MongoDB), optional email notifications, and background queue processing with Bull. Ideal for modern apps needing instant alerts, multi-channel delivery, and scalability.

Installation

CLI

npx backternity add notifications-websocket

What This Does

Installs a fully functional WebSocket notification system with real-time delivery, persistence, and multi-channel support (socket, email, queue).

Files & Folders Created

File / Path	Description
/src/config/websocket.js	Initializes the Socket.IO server and manages client connections.
/src/models/notification.js	MongoDB schema for storing notification data.
/src/config/email.js	Configures Nodemailer for optional email notifications.
/src/config/queue.js	Sets up Bull queue for background message processing.
/src/services/notificationService.js	Core service for creating and managing notifications.
/src/routes/notifications.js	REST routes for creating, listing, and marking notifications.
/server.js.example	Example server with integrated WebSocket and Express routing.

Files to be modified

File / Path	Description
server.js	Adds WebSocket initialization and notification API routes.
.env	Adds WebSocket, SMTP, and queue environment variables.

Configuration

# WebSocket Notifications Configuration
PORT=3001
ENABLE_EMAIL_NOTIFICATIONS=true
NOTIFICATION_QUEUE_ENABLED=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=YourApp Notifications <your-email@gmail.com>

Frontend Integration

Integrate in your Next.js or React app to receive instant real-time notifications. Users join their own private WebSocket room to receive personalized alerts.

POST/api/notifications

Send a new notification via WebSocket, email, or queue.

GET/api/notifications/:userId

Fetch notifications for a user (supports unread filtering).

PATCH/api/notifications/:id/read

Mark a notification as read.

Example

// app/notifications/NotificationClient.jsx (Next.js example)
'use client';
import { useEffect, useState } from 'react';
import { io } from 'socket.io-client';

export default function NotificationClient({ userId }) {
  const [notifications, setNotifications] = useState([]);
  const [connected, setConnected] = useState(false);

  useEffect(() => {
    const socket = io('http://localhost:3001', { transports: ['websocket'] });

    socket.on('connect', () => {
      setConnected(true);
      socket.emit('join', userId);
      console.log('🔗 Connected to WebSocket server');
    });

    socket.on('notification', (data) => {
      setNotifications((prev) => [data, ...prev]);
    });

    socket.on('disconnect', () => {
      setConnected(false);
      console.log('❌ Disconnected from server');
    });

    return () => socket.disconnect();
  }, [userId]);

  return (
    <div className="p-4 border border-white/10 rounded-lg bg-black/30">
      <h3 className="text-lg font-semibold mb-2 text-white">
        🔔 Notifications {connected ? '🟢' : '🔴'}
      </h3>
      {notifications.length === 0 ? (
        <p className="text-sm text-muted-foreground">No notifications yet...</p>
      ) : (
        <ul className="space-y-2 max-h-[250px] overflow-y-auto [&::-webkit-scrollbar]:w-0 scrollbar-none">
          {notifications.map((n) => (
            <li
              key={n._id}
              className="text-sm text-foreground border border-white/10 rounded-md p-2"
            >
              <strong className="text-emerald-400">{n.title}</strong>
              <p className="text-xs text-muted-foreground">{n.message}</p>
              <span className="text-[10px] text-gray-500 block mt-1">
                {n.type.toUpperCase()} • {n.priority.toUpperCase()}
              </span>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Usage

// Programmatic usage example
const { createNotification } = require('./src/services/notificationService');

await createNotification({
  userId: '507f1f77bcf86cd799439011',
  title: 'New message received',
  message: 'You have a new message from Jane.',
  type: 'info',
  priority: 'normal',
  channels: ['socket', 'email'],
  metadata: { email: 'user@example.com' }
});