Using the Page Visibility API to Pause Event Streams #Permalink to this section

Part of Mobile & Background-Tab Handling.

An EventSource connection stays open indefinitely by design — the browser holds a persistent TCP connection and the server keeps a slot allocated for it. When the user switches tabs, locks their phone, or moves the app to the background, the connection keeps flowing: the server sends events, the browser buffers them silently, and mobile radios stay active. On a device with 50 open browser tabs this multiplies into real battery drain and wasted server file descriptors.

The Page Visibility API solves this cleanly. Listening to document.visibilitychange lets you tear down the EventSource when the page goes hidden and rebuild it — with the correct Last-Event-ID — when the page becomes visible again. No polling, no timers, no framework magic required.

Symptom & Developer Intent #Permalink to this section

Observable behaviors that lead engineers here:

• Mobile users report faster battery drain on pages that use live feeds.
• Server connection counts remain high even when most users are idle (background tabs).
• Chrome DevTools Network panel shows an open SSE stream with no traffic for minutes while the tab is in the background.
• Memory profiles show event data accumulating in a hidden tab’s JavaScript heap.
• Load tests show that concurrent connection counts don’t drop even when all browser windows are backgrounded.

The developer intent is to disconnect the EventSource when document.hidden === true and reconnect with the last received event ID when document.hidden === false, so no server slot is wasted on an invisible tab and no client-side buffer grows unbounded.

Root Cause Analysis #Permalink to this section

Why EventSource Keeps Running in the Background #Permalink to this section

The SSE protocol specifies nothing about application-layer lifecycle: the browser’s EventSource implementation is a streaming HTTP client. It opens a connection, reads until the server closes it or a network error occurs, then waits retry milliseconds and reconnects. It has no awareness of tab visibility.

Browsers throttle JavaScript timers and requestAnimationFrame for hidden tabs, but they do not suspend active HTTP responses. The reason is intentional: browser specs assume that a backgrounded tab might be legitimately receiving background data (push notifications, progress updates). So EventSource is exempt from throttling.

The practical consequences at the protocol level:

Why the Default Reconnect Behavior Doesn’t Help #Permalink to this section

The event ID and retry mechanism is designed for accidental disconnections, not intentional ones. If you just set eventSource.close() without storing the last ID, the browser forgets it. On reconnect, EventSource sends no Last-Event-ID header and the server replays nothing — you silently lose events that arrived during the hidden interval.

Correct pausing requires two coordinated pieces: storing the last seen id field and passing it back via the URL or request header on reconnect.

Step-by-Step Resolution #Permalink to this section

Step 1 — Track the Last Received Event ID #Permalink to this section

Intercept every message event (and any named events) to capture the current ID before you might close the connection.

// visibility-sse.js

let lastEventId = null;

function attachIdTracker(es) {
  // The browser exposes the running last-event-id as es.url is not helpful;
  // we must capture it from each event ourselves.
  es.addEventListener('message', (e) => {
    if (e.lastEventId) lastEventId = e.lastEventId;
    handleEvent(e);
  });

  // If you use named event types, mirror the tracking there too.
  es.addEventListener('update', (e) => {
    if (e.lastEventId) lastEventId = e.lastEventId;
    handleUpdate(e);
  });
}

MessageEvent.lastEventId reflects the most recent id: field seen in the stream — it persists across event types on the same connection, matching the WHATWG spec’s “last event ID” buffer.

Step 2 — Build a Connect/Disconnect Helper #Permalink to this section

Encapsulate open and close so the visibility handler stays simple.

// visibility-sse.js (continued)

const SSE_BASE = '/api/events';
let es = null;

function connect() {
  if (es && es.readyState !== EventSource.CLOSED) return; // already open

  const url = new URL(SSE_BASE, location.origin);
  if (lastEventId !== null) {
    // Pass the last ID as a query param; read it server-side and emit
    // a synthetic `id:` field on the first event so the browser resumes.
    url.searchParams.set('lastEventId', lastEventId);
  }

  es = new EventSource(url.toString(), { withCredentials: true });
  attachIdTracker(es);

  es.onerror = (e) => {
    console.warn('SSE error', e, 'readyState:', es.readyState);
    // EventSource will retry automatically on transient errors;
    // only hard-close on intentional visibility-driven pauses.
  };
}

function disconnect() {
  if (!es) return;
  es.close(); // sets readyState to CLOSED immediately; no retry fires
  es = null;
}

Note on Last-Event-ID header vs query param: The browser sends Last-Event-ID as a request header automatically only when it internally reconnects after a network failure. When you call new EventSource(url) from scratch, the browser sends no such header. Passing the ID as a query parameter is the standard workaround — your server reads it and fast-forwards the stream accordingly.

Step 3 — Wire Up visibilitychange #Permalink to this section

// visibility-sse.js (continued)

function handleVisibilityChange() {
  if (document.hidden) {
    disconnect();
  } else {
    connect();
  }
}

// Initial connect on page load (only if already visible).
if (!document.hidden) {
  connect();
}

document.addEventListener('visibilitychange', handleVisibilityChange);

The visibilitychange event fires on:

• Tab switch (foreground → background and back)
• Alt+Tab or Cmd+Tab away from the browser
• Phone screen lock / unlock
• Browser window minimise (on some platforms)
• Mobile browser moving to background (home button, swipe up)

Step 4 — React Hook (Production Pattern) #Permalink to this section

For React apps, encapsulate the entire lifecycle in a hook that is safe under Strict Mode double-mount.

// useVisibilitySSE.ts
import { useEffect, useRef, useCallback } from 'react';

type MessageHandler = (event: MessageEvent) => void;

export function useVisibilitySSE(
  url: string,
  onMessage: MessageHandler,
  eventTypes: string[] = []
) {
  const esRef = useRef<EventSource | null>(null);
  const lastIdRef = useRef<string | null>(null);
  // Stable ref to avoid re-registering on every render
  const onMessageRef = useRef(onMessage);
  onMessageRef.current = onMessage;

  const connect = useCallback(() => {
    if (esRef.current?.readyState === EventSource.OPEN) return;

    const target = new URL(url, location.origin);
    if (lastIdRef.current) {
      target.searchParams.set('lastEventId', lastIdRef.current);
    }

    const es = new EventSource(target.toString(), { withCredentials: true });

    const track = (e: MessageEvent) => {
      if (e.lastEventId) lastIdRef.current = e.lastEventId;
      onMessageRef.current(e);
    };

    es.addEventListener('message', track);
    eventTypes.forEach((type) => es.addEventListener(type, track as EventListener));

    esRef.current = es;
  }, [url, eventTypes]);

  const disconnect = useCallback(() => {
    esRef.current?.close();
    esRef.current = null;
  }, []);

  useEffect(() => {
    if (!document.hidden) connect();

    const onVisibility = () => (document.hidden ? disconnect() : connect());
    document.addEventListener('visibilitychange', onVisibility);

    return () => {
      document.removeEventListener('visibilitychange', onVisibility);
      disconnect(); // clean up on unmount
    };
  }, [connect, disconnect]);
}

Usage:

// LiveFeed.tsx
import { useVisibilitySSE } from './useVisibilitySSE';

export function LiveFeed() {
  useVisibilitySSE('/api/feed', (e) => {
    const data = JSON.parse(e.data);
    // dispatch to store, update state, etc.
  }, ['update', 'delete']);

  return <div>...</div>;
}

Step 5 — Server-Side: Resume from lastEventId #Permalink to this section

The client reconnect is only useful if the server can replay missed events. A minimal Node.js example using an in-memory ring buffer:

// server.js (Node.js / Express)
const RING_BUFFER_SIZE = 500;
const ringBuffer = []; // { id, data, type }

app.get('/api/events', (req, res) => {
  res.set({
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache, no-transform',
    'Connection': 'keep-alive',
    'X-Accel-Buffering': 'no',   // disable nginx proxy buffering
  });
  res.flushHeaders();

  const lastId = req.query.lastEventId ?? req.headers['last-event-id'];
  if (lastId) {
    // Replay events the client missed while hidden
    const idx = ringBuffer.findIndex((e) => e.id === lastId);
    const missed = idx >= 0 ? ringBuffer.slice(idx + 1) : [];
    missed.forEach((e) => {
      res.write(`id: ${e.id}\nevent: ${e.type}\ndata: ${e.data}\n\n`);
    });
  }

  // Register this connection for future broadcasts
  addSubscriber(req, res);

  req.on('close', () => removeSubscriber(res));
});

For Redis pub/sub fan-out across multiple server nodes, store the ring buffer in a Redis sorted set keyed by event ID so any node can replay missed events.

Validation & Monitoring #Permalink to this section

DevTools Verification #Permalink to this section

1. Open the page, verify the SSE stream appears in Network → EventStream with events arriving.
2. Switch to a different tab. Return to DevTools — the stream entry should disappear (connection closed) within ~100 ms of visibilitychange.
3. Switch back to the tab. A new SSE request should appear with ?lastEventId=<id> in the URL.
4. Check the Response Headers of the new request confirm Content-Type: text/event-stream.

curl Smoke Test for Resume #Permalink to this section

# Confirm the server accepts lastEventId and replays missed events
curl -N \
  -H "Accept: text/event-stream" \
  "https://your-api.example.com/api/events?lastEventId=42" \
  2>/dev/null | head -20
# Expected: id: 43, id: 44, ... events replayed before live stream

Unit Test Stub (Vitest / jsdom) #Permalink to this section

// useVisibilitySSE.test.ts
import { renderHook } from '@testing-library/react';
import { useVisibilitySSE } from './useVisibilitySSE';

it('closes EventSource when tab becomes hidden', () => {
  const handler = vi.fn();
  renderHook(() => useVisibilitySSE('/api/events', handler));

  const firstEs = globalThis.__lastEventSource; // injected by mock
  expect(firstEs.readyState).toBe(EventSource.OPEN);

  // Simulate tab hide
  Object.defineProperty(document, 'hidden', { value: true, configurable: true });
  document.dispatchEvent(new Event('visibilitychange'));

  expect(firstEs.close).toHaveBeenCalledOnce();
});

it('reopens with lastEventId when tab becomes visible', () => {
  // ... set lastEventId via fired message, then toggle visibility
});

Verification Checklist #Permalink to this section

• visibilitychange listener is added on mount and removed on unmount / component destroy.
• EventSource.close() is called (not just reassigned) when document.hidden becomes true.
• Last received e.lastEventId is persisted to a ref or module variable before closing.
• Reconnect URL includes ?lastEventId=<value> when a prior ID exists.
• Server reads lastEventId from query param (not only from the Last-Event-ID header) and replays the ring buffer.
• DevTools Network tab confirms the SSE connection disappears on tab switch and reappears on tab focus.
• No duplicate visibilitychange listeners (React Strict Mode double-invoke, multiple hook instances) — guard with a single global listener or AbortController.
• withCredentials: true is preserved on the reconnected EventSource if authentication uses cookies.

Frequently Asked Questions #Permalink to this section

Related #Permalink to this section

• Mobile & Background-Tab Handling
• Resuming SSE Streams After Mobile Tab Suspension
• Event ID & Retry Mechanism Design
• Error Handling & Reconnection UX
• Redis Pub/Sub Fan-Out for SSE