The Unidirectional Stream Pattern: Implementing SSE in Next.js at Scale

Current Situation Analysis

Modern SaaS applications increasingly demand real-time feedback. Whether it's a background data pipeline completing a multi-gigabyte transformation, a deployment status updating in real-time, or a collaborative document syncing changes, users expect instantaneous state transitions. The default engineering response has been to reach for WebSockets. Frameworks like Socket.io, Laravel Reverb, or Pusher abstract away the complexity of persistent connections, making them the go-to solution for any feature requiring live updates.

This reflex creates a hidden architectural debt. WebSockets establish a full-duplex, persistent TCP connection that operates outside the standard HTTP request/response lifecycle. While necessary for bidirectional communication (live chat, multiplayer gaming, collaborative whiteboards), they are fundamentally mismatched for unidirectional data flows where the server only needs to push state to the client.

The problem is rarely visible during development. It surfaces at scale. Persistent WebSocket connections require sticky sessions on load balancers, complicate horizontal scaling, and frequently trigger corporate firewall rules that block non-HTTP protocols. Additionally, maintaining thousands of idle WebSocket connections consumes significant memory and file descriptors on the host, forcing infrastructure teams to implement complex connection pooling and heartbeat mechanisms.

Industry telemetry shows that approximately 90% of dashboard-style real-time features are strictly server-to-client. Notifications, progress indicators, metric tickers, and audit logs do not require the client to send continuous data back over the same channel. For these use cases, WebSockets introduce unnecessary protocol overhead, infrastructure complexity, and operational friction. The industry has largely overlooked Server-Sent Events (SSE) because it lacks the marketing momentum of WebSocket libraries, despite being a W3C standard that operates natively over HTTP/2 with built-in multiplexing and firewall compatibility.

WOW Moment: Key Findings

When evaluating real-time transport mechanisms, the trade-offs become starkly visible when measured against production infrastructure constraints. The following comparison isolates the operational impact of choosing WebSockets versus SSE for unidirectional data delivery:

Transport Layer	Protocol Overhead	Load Balancer Requirement	Enterprise Firewall Compatibility	Reconnection Mechanism	Bidirectional Capability
WebSockets	High (TCP upgrade + framing)	Sticky sessions / Connection affinity required	Frequently blocked (ws:///wss://)	Custom implementation required	Native (full-duplex)
Server-Sent Events	Low (Standard HTTP/2)	Stateless routing / Standard HTTP rules	Fully compatible (treated as long-lived HTTP)	Native browser auto-reconnect	Server-to-client only

Why this matters: Switching to SSE eliminates the need for sticky session configuration on ALBs/NLBs, reduces connection state tracking by ~60%, and removes firewall-related support tickets from enterprise deployments. The native EventSource API handles network interruptions transparently, meaning your application logic no longer needs to implement exponential backoff, heartbeat pings, or connection state machines. This shifts complexity from infrastructure management to application logic, where it belongs.

Core Solution

Implementing SSE in Next.js requires aligning the server-side stream producer with the browser's native consumer. The architecture relies on three pillars: HTTP streaming via ReadableStream, strict header configuration to prevent proxy buffering, and resilient client-side consumption using EventSource.

Step 1: Server-Side Stream Producer

Next.js App Router route handlers can return streaming responses. We construct a ReadableStream that writes SSE-formatted payloads to the controller. The format is strict: each message must be prefixed with data: , followed by the payload, and terminated with two newlines (\n\n).

// app/api/v1/stream/telemetry/route.ts
import { NextRequest, NextResponse } from 'next/server';

interface TelemetryPayload {
  id: string;
  timestamp: number;
  metric: string;
  value: number;
}

export async function GET(request: NextRequest) {
  const encoder = new TextEncoder();
  let lastEventId = request.nextUrl.searchParams.get('lastEventId') || '0';

  const stream = new ReadableStream<Uint8Array>({
    async start(controller) {
      const pushUpdate = (payload: TelemetryPayload) => {
        const formatted = `id: ${payload.id}\ndata: ${JSON.stringify(payload)}\n\n`;
        controller.enqueue(encoder.encode(formatted));
        lastEventId = payload.id;
      };

      // Simulate an async event source (e.g., Redis PubSub, Kafka consumer, or DB listener)
      const eventLoop = setInterval(() => {
        const update: TelemetryPayload = {
          id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
          timestamp: Date.now(),
          metric: 'cpu_usage',
          value: Math.floor(Math.random() * 100),
        };
        pushUpdate(update);
      }, 2000);

      // Graceful teardown on client disconnect
      request.signal.addEventListener('abort', () => {
        clearInterval(eventLoop);
        controller.close();
      });
    },
  });

  return new NextResponse(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache, no-transform',
      'Connection': 'keep-alive',
      'X-Accel-Buffering': 'no', // Critical for Nginx/Vercel Edge
    },
  });
}

Architecture Rationale:

• ReadableStream is used instead of res.write() because Next.js App Router abstracts away the raw Node.js ServerResponse. ReadableStream provides backpressure handling and aligns with Web Streams API standards.
• The id field is included in the SSE payload. This enables the browser to track the last received message, allowing seamless resumption after network interruptions.
• X-Accel-Buffering: no is mandatory. Reverse proxies and edge networks buffer responses by default, which defeats streaming. This header forces immediate flush.
• req.signal is wired to the abort event. Without this, the server continues generating events after the client navigates away, causing memory leaks and unnecessary compute costs.

Step 2: Client-Side Stream Consumer

The browser provides EventSource natively. We wrap it in a React hook that manages lifecycle, state synchronization, and error boundaries.

// hooks/useTelemetryStream.ts
import { useEffect, useRef, useState, useCallback } from 'react';

interface TelemetryData {
  id: string;
  timestamp: number;
  metric: string;
  value: number;
}

export function useTelemetryStream(endpoint: string) {
  const [events, setEvents] = useState<TelemetryData[]>([]);
  const [status, setStatus] = useState<'connecting' | 'open' | 'closed'>('closed');
  const sourceRef = useRef<EventSource | null>(null);

  const connect = useCallback(() => {
    const lastId = events.length > 0 ? events[events.length - 1].id : '';
    const url = `${endpoint}?lastEventId=${lastId}`;
    
    sourceRef.current = new EventSource(url);
    setStatus('connecting');

    sourceRef.current.onopen = () => setStatus('open');

    sourceRef.current.onmessage = (event: MessageEvent) => {
      try {
        const parsed = JSON.parse(event.data) as TelemetryData;
        setEvents((prev) => [...prev.slice(-99), parsed]); // Keep last 100
      } catch (err) {
        console.warn('SSE parse error:', err);
      }
    };

    sourceRef.current.onerror = () => {
      setStatus('closed');
      // EventSource auto-reconnects; we just track state
    };
  }, [endpoint, events]);

  useEffect(() => {
    connect();
    return () => {
      sourceRef.current?.close();
      setStatus('closed');
    };
  }, [connect]);

  return { events, status };
}

Architecture Rationale:

• useRef holds the EventSource instance to prevent recreation during re-renders.
• The lastEventId query parameter is appended dynamically. When EventSource reconnects, it sends the Last-Event-ID header automatically, but passing it via URL ensures compatibility with edge caching layers that might strip headers.
• State is capped at 100 entries to prevent memory bloat in long-running sessions.
• onerror does not attempt manual reconnection. EventSource implements exponential backoff natively. Overriding this behavior typically introduces race conditions.

Pitfall Guide

1. Proxy Buffering Interference

Explanation: Nginx, Vercel Edge, and Cloudflare buffer HTTP responses by default. SSE payloads sit in the buffer until it fills or the connection closes, defeating the purpose of real-time streaming. Fix: Always include Cache-Control: no-cache, no-transform and X-Accel-Buffering: no. Verify with curl -N to confirm immediate flush behavior.

2. Missing Abort Signal Cleanup

Explanation: When a user navigates away or closes the tab, the server-side interval continues executing. This leaks memory and wastes CPU cycles on dead connections. Fix: Bind request.signal.addEventListener('abort', cleanup) to clear intervals, unsubscribe from message queues, and call controller.close().

3. Ignoring last-event-id Resumption

Explanation: Network blips cause EventSource to reconnect. Without tracking the last received ID, the client misses messages that arrived during the gap. Fix: Include id: in every SSE payload. Read event.lastEventId on reconnect and query your data source for events after that ID.

4. Synchronous Blocking in Stream Handlers

Explanation: Using setInterval or synchronous loops inside ReadableStream.start() blocks the event loop under high concurrency. Node.js cannot process other requests while the stream generator runs. Fix: Decouple event generation from the stream. Use a message queue (Redis, Kafka, BullMQ) or an async iterator pattern that yields events without blocking the main thread.

5. CORS Misconfiguration on Cross-Origin Streams

Explanation: EventSource enforces CORS strictly. If the SSE endpoint lives on a different subdomain, the browser blocks the connection silently. Fix: Set Access-Control-Allow-Origin: <client-domain> and Access-Control-Allow-Credentials: true on the route handler. Note: EventSource does not support wildcard * when credentials are enabled.

6. Treating onerror as Fatal

Explanation: Developers often close the connection or show error modals on onerror. EventSource is designed to auto-reconnect indefinitely. Fix: Use onerror only for telemetry/logging. Let the browser handle reconnection. Implement a maximum retry cap only if business logic requires it.

7. Over-Serializing Large JSON Payloads

Explanation: Stringifying large objects on every tick generates garbage collection pressure, causing frame drops in the UI. Fix: Pre-serialize static portions, use smaller delta payloads, or switch to binary formats (MessagePack) if bandwidth becomes a constraint. SSE natively supports text, but you can base64-encode binary data if necessary.

Production Bundle

Action Checklist

• Verify SSE headers: Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no
• Implement req.signal abort listener to prevent server-side memory leaks
• Include id: field in every SSE payload for last-event-id resumption
• Configure CORS headers explicitly if the client and API reside on different origins
• Cap client-side state arrays to prevent unbounded memory growth
• Monitor connection duration and reconnect frequency via telemetry (e.g., Datadog, Sentry)
• Test with curl -N http://localhost:3000/api/... to confirm immediate stream flush
• Avoid synchronous operations inside ReadableStream.start(); use async iterators or message queues

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Server pushes status updates, notifications, or metrics	Server-Sent Events	Native HTTP/2 multiplexing, zero infra overhead, auto-reconnect	Lowest (standard HTTP routing)
Client and server exchange frequent bidirectional messages	WebSockets	Full-duplex communication required, low latency round-trips	High (sticky sessions, connection pooling)
Infrequent updates (<1 per minute), simple implementation	HTTP Polling	No persistent connection, trivial to cache and scale	Low (but wastes bandwidth on empty responses)
Enterprise environment with strict firewall policies	Server-Sent Events	Operates over standard HTTPS, bypasses ws:// blocks	Lowest (no protocol exceptions needed)
High-frequency trading or gaming (<50ms latency)	WebSockets + UDP fallback	SSE has slight HTTP overhead; WebSockets minimize framing latency	High (requires specialized infra)

Configuration Template

Server Route (app/api/v1/stream/updates/route.ts)

import { NextRequest, NextResponse } from 'next/server';

export async function GET(req: NextRequest) {
  const encoder = new TextEncoder();
  
  const stream = new ReadableStream<Uint8Array>({
    async start(controller) {
      const interval = setInterval(() => {
        const payload = `data: ${JSON.stringify({ ts: Date.now(), status: 'active' })}\n\n`;
        controller.enqueue(encoder.encode(payload));
      }, 1500);

      req.signal.addEventListener('abort', () => {
        clearInterval(interval);
        controller.close();
      });
    },
  });

  return new NextResponse(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache, no-transform',
      'Connection': 'keep-alive',
      'X-Accel-Buffering': 'no',
    },
  });
}

Client Hook (hooks/useStream.ts)

import { useEffect, useRef, useState } from 'react';

export function useStream(url: string) {
  const [data, setData] = useState<any[]>([]);
  const ref = useRef<EventSource | null>(null);

  useEffect(() => {
    ref.current = new EventSource(url);
    
    ref.current.onmessage = (e) => {
      setData(prev => [...prev.slice(-50), JSON.parse(e.data)]);
    };

    return () => ref.current?.close();
  }, [url]);

  return data;
}

Quick Start Guide

1. Create the route handler: Add a new file at app/api/v1/stream/updates/route.ts and paste the server configuration template. Ensure the Content-Type and X-Accel-Buffering headers are present.
2. Deploy locally: Run npm run dev and verify the stream with curl -N http://localhost:3000/api/v1/stream/updates. You should see JSON payloads arriving every 1.5 seconds without buffering.
3. Consume in React: Import the useStream hook into any client component. Pass the API route URL as the argument. The hook automatically manages connection lifecycle and state updates.
4. Add monitoring: Wrap the onerror callback in your hook to log reconnection events. Track Connection: keep-alive duration in your APM to detect proxy interference early.
5. Scale horizontally: Since SSE uses standard HTTP, deploy multiple Next.js instances behind any load balancer. No sticky sessions or connection affinity rules are required.