Building Low-Latency Real-Time Dashboards: Server-Sent Events (SSE) vs. WebSockets in Next.js

// app/api/stream/metrics/route.ts
import { NextRequest } from "next/server";

export const runtime = "edge"; // Run on Edge runtime for sub-second global streaming

export async function GET(request: NextRequest) {
  const encoder = new TextEncoder();

  // Create a ReadableStream for server-pushed events
  const stream = new ReadableStream({
    async start(controller) {
      let counter = 0;

      // Send initial connection event
      controller.enqueue(
        encoder.encode(`event: connected\ndata: ${JSON.stringify({ status: "ready" })}\n\n`)
      );

      // Periodically push live metrics payload
      const interval = setInterval(() => {
        counter++;
        const payload = {
          timestamp: new Date().toISOString(),
          activeUsers: Math.floor(Math.random() * 500) + 1200,
          requestsPerSecond: Math.floor(Math.random() * 50) + 300,
          cpuUsage: (Math.random() * 20 + 15).toFixed(1),
        };

        // Standard SSE format: id, event, data payload ending with double newline \n\n
        const eventData = `id: ${counter}\nevent: metrics-update\ndata: ${JSON.stringify(payload)}\n\n`;
        controller.enqueue(encoder.encode(eventData));

        if (counter >= 100) {
          clearInterval(interval);
          controller.close();
        }
      }, 2000);

      // Clean up timer if stream is aborted by client disconnect
      request.signal.addEventListener("abort", () => {
        clearInterval(interval);
        controller.close();
      });
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      "Connection": "keep-alive",
      "X-Accel-Buffering": "no", // Disable NGINX / proxy response buffering
    },
  });
}

// components/MetricsDashboard.tsx
"use client";

import { useEffect, useState } from "react";

interface Metrics {
  timestamp: string;
  activeUsers: number;
  requestsPerSecond: number;
  cpuUsage: string;
}

export default function MetricsDashboard() {
  const [metrics, setMetrics] = useState<Metrics | null>(null);
  const [connected, setConnected] = useState(false);

  useEffect(() => {
    // 1. Initialize EventSource to listen to Next.js route
    const eventSource = new EventSource("/api/stream/metrics/");

    eventSource.addEventListener("connected", () => {
      setConnected(true);
    });

    // 2. Listen for custom event type
    eventSource.addEventListener("metrics-update", (e: MessageEvent) => {
      const data: Metrics = JSON.parse(e.data);
      setMetrics(data);
    });

    eventSource.onerror = (err) => {
      console.error("SSE connection error:", err);
      setConnected(false);
    };

    // 3. Clean up on unmount
    return () => {
      eventSource.close();
    };
  }, []);

  return (
    <div className="p-6 rounded-2xl bg-white/5 border border-white/10 text-white">
      <div className="flex items-center gap-3 mb-4">
        <span className={`w-3 h-3 rounded-full ${connected ? "bg-brand animate-pulse" : "bg-red-500"}`} />
        <h3 className="font-bold text-lg">Live Analytics Stream</h3>
      </div>
      {metrics ? (
        <div className="grid grid-cols-3 gap-4 font-mono text-sm">
          <div>Users: <span className="text-brand">{metrics.activeUsers}</span></div>
          <div>RPS: <span className="text-brand">{metrics.requestsPerSecond}</span></div>
          <div>CPU: <span className="text-brand">{metrics.cpuUsage}%</span></div>
        </div>
      ) : (
        <p className="text-xs text-muted">Connecting to stream...</p>
      )}
    </div>
  );
}