How to Handle Streaming Data in React Without Freezing the UI

1. Buffer incoming WebSocket or SSE messages in a mutable useRef array outside React state.
2. Flush the buffer into state once per frame using a requestAnimationFrame loop.
3. Collapse all buffered messages into a single setState call per animation frame.
4. Memoize child components with React.memo and custom comparators to skip unnecessary re-renders.
5. Virtualize long lists with @tanstack/react-virtual to keep DOM node count constant.
6. Cap state array length with a maxBufferSize option to prevent memory leaks on indefinite streams.
7. Bypass React entirely for ultra-high-frequency single-value updates by writing to the DOM via refs.

If you're building anything that consumes react streaming data from a backend, whether that's an AI chat interface, a financial dashboard, or a multiplayer collaboration tool, you've already felt the pain. WebSocket React performance degrades fast when messages arrive every 50 milliseconds, each one triggering a state update that kicks off React's full reconciliation cycle.

This article builds a production-ready useServerStream hook that unifies WebSocket and SSE transports behind a single API, using requestAnimationFrame batching and ref-based buffering to keep your UI smooth no matter how fast the backend pushes data.

Table of Contents

• The Problem: Why React Falls Apart on High-Frequency Streams
• Architecture Principles for Streaming Data in React
• Building the useServerStream Hook: SSE Implementation
• Extending to WebSockets
• Controlling What Re-renders: Component-Level Strategies
• Putting It All Together: LLM Token Stream Demo
• Production Hardening Checklist
• Key Takeaways

The Problem: Why React Falls Apart on High-Frequency Streams

What Happens Inside React When State Updates Every 50ms

React's render pipeline follows a predictable sequence: a setState call schedules an update, React runs the render phase (building a new virtual DOM tree and diffing it against the previous one), then commits mutations to the real DOM, and finally the browser paints. The official React docs call this the "Render and Commit" cycle.

When a WebSocket fires 20 messages per second and each message calls setState, you're scheduling 20 render cycles per second at minimum. Each cycle diffs the entire component subtree unless you've explicitly blocked it with memoization. For a component tree of any real complexity, that means hundreds or thousands of virtual DOM node comparisons per second. Most of them produce identical results.

React 18's automatic batching helps in many scenarios. Under createRoot, React batches state updates that happen within the same event handler or microtask into a single render pass. The official React 18 upgrade guide says exactly this. But the practical benefit depends heavily on timing. When WebSocket or SSE onmessage callbacks fire in rapid succession but across separate event loop tasks, you may still see more render cycles than expected. The batching works, but it can't collapse 20 independent asynchronous callbacks firing at unpredictable intervals into a single update. Each callback that fires after the previous render has already been scheduled triggers its own cycle.

Here's the naive implementation that causes the render storm:

// ❌ Naive implementation — render storm generator
function useChatStream(url: string) {
  const [messages, setMessages] = useState<string[]>([]);

  useEffect(() => {
    const ws = new WebSocket(url);

    ws.onmessage = (event) => {
      const token = JSON.parse(event.data).token;
      // 🔴 This fires on EVERY incoming message.
      // At 30 tokens/sec, React schedules up to 30 renders/sec.
      // Each render diffs the entire messages array and all children.
      setMessages((prev) => [...prev, token]);
    };

    return () => ws.close();
  }, [url]);

  return messages;
}

The setMessages call on line 9 is the culprit. Every incoming token creates a new array, triggers reconciliation, and forces React to diff every child component that depends on messages. At 30 tokens per second, the main thread barely has time to breathe.

Profiling the Damage: A Before Baseline

To see the impact, open React DevTools Profiler and hit record while your stream is active. You'll see a wall of tiny commits, each taking 5 to 15ms in a simple app, ballooning to 50ms or more once your component tree has real content. Switch to the Chrome Performance panel and look for long tasks (anything over 50ms gets flagged with a red corner). They'll be stacked up, blocking input event processing and causing visible scroll jank.

For the benchmarks in this article, I used two scenarios: an LLM token stream arriving at roughly 30 tokens per second (simulating a ChatGPT-style interface), and a stock ticker pushing 20 price updates per second across 50 symbols. I ran all tests on a production build (React 18.3, StrictMode off) in Chrome on an M2 MacBook Pro. Dev mode exaggerates render costs significantly, so always profile production builds for meaningful numbers.

React 18 also gives you startTransition and useTransition for marking updates as non-urgent. Wrapping setState in startTransition tells React it can interrupt the render to keep input responsive. Useful lever for streaming scenarios, though it doesn't eliminate the core problem of too many render cycles.

Architecture Principles for Streaming Data in React

Separate Transport from Render

The fundamental architectural principle: your network layer should never directly drive React renders. Instead, it buffers incoming data outside React's state system, and a display-synchronized loop flushes snapshots into state at a cadence the renderer can handle.

The data flow looks like this:

Transport (WS/SSE) → Mutable Buffer (useRef, outside React) → RAF tick → single setState → Render

The transport writes to a plain JavaScript array held in a useRef. A requestAnimationFrame loop reads that buffer, calls setState once with the accumulated messages, and clears the buffer. React sees one update per frame instead of one update per message.

The Three Levers: Buffering, Throttling, and Selective Rendering

Buffering means accumulating messages in a mutable ref between animation frames. The ref lives outside React's state tracking, so writing to it triggers zero renders. This is the critical decoupling point.

The ref lives outside React's state tracking, so writing to it triggers zero renders. This is the critical decoupling point.

Throttling via requestAnimationFrame aligns your state updates to the browser's display refresh rate. On a 60Hz display, that's roughly one flush every 16.67ms. On a 120Hz display, you get double the updates. Unlike setInterval(fn, 16), RAF automatically pauses in background tabs and synchronizes with the compositor, avoiding wasted work. Background tabs throttle RAF heavily (most browsers cap it around 1fps or less), which is actually what you want since there's no point rendering to a tab nobody's looking at.

Selective Rendering makes sure that when the batched update does hit React, only the components that genuinely changed re-render. React.memo with custom comparators, useMemo for derived values, and list virtualization all cut the DOM work per commit.

One more tool worth knowing: useSyncExternalStore is React 18's official hook for subscribing to external mutable data sources with correct concurrent rendering semantics. If your buffer logic grows complex or needs to be shared across components, wrapping it in an external store and subscribing via useSyncExternalStore is the most "React-correct" approach.

Building the useServerStream Hook: SSE Implementation

Hook API Design

The hook exposes a clean, generic API that works for both LLM token streams (where T is string) and structured data (where T might be { symbol: string; price: number }):

type StreamStatus = 'connecting' | 'open' | 'closed' | 'error';

interface UseServerStreamOptions<T> {
  transport: 'sse' | 'ws';
  batchInterval?: 'raf' | number; // default: 'raf'
  maxBufferSize?: number;         // default: 10_000
  onMessage?: (msg: T) => void;   // escape hatch for non-React updates
  onOverflow?: (dropped: number) => void;
  parse?: (raw: string) => T;     // default: JSON.parse
}

interface UseServerStreamReturn<T> {
  data: T[];
  status: StreamStatus;
  error: Event | null;
  close: () => void;
}

function useServerStream<T>(
  url: string,
  options: UseServerStreamOptions<T>
): UseServerStreamReturn<T>;

The generic T parameter gives consumers full type safety. The onMessage callback is an escape hatch for scenarios where you want to update the DOM directly without going through React state (more on that later). The parse function defaults to JSON.parse but you can override it for custom serialization formats.

SSE Transport with RAF Batching

Here's the full SSE implementation. The key insight: the onmessage handler never touches React state. It only pushes to a mutable ref. The RAF loop is the sole writer to state:

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

// Requires the UseServerStreamOptions, UseServerStreamReturn, and StreamStatus
// types defined in the "Hook API Design" section above.

function useServerStream<T = string>(
  url: string,
  options: UseServerStreamOptions<T>
): UseServerStreamReturn<T> {
  const {
    transport,
    batchInterval = 'raf',
    maxBufferSize = 10_000,
    onMessage,
    onOverflow,
    parse = (raw: string) => JSON.parse(raw) as T,
  } = options;

  const [data, setData] = useState<T[]>([]);
  const [status, setStatus] = useState<StreamStatus>('connecting');
  const [error, setError] = useState<Event | null>(null);

  const bufferRef = useRef<T[]>([]);
  const rafRef = useRef<number>(0);
  const sourceRef = useRef<EventSource | null>(null);

  // Stable refs for callbacks to avoid re-running effects when they change
  const onOverflowRef = useRef(onOverflow);
  onOverflowRef.current = onOverflow;
  const onMessageRef = useRef(onMessage);
  onMessageRef.current = onMessage;
  const parseRef = useRef(parse);
  parseRef.current = parse;

  // RAF flush loop: reads buffer, writes to state once per frame
  const startFlushLoop = useCallback(() => {
    const flush = () => {
      if (bufferRef.current.length > 0) {
        const batch = bufferRef.current;
        bufferRef.current = [];
        setData((prev) => {
          const next = [...prev, ...batch];
          // Cap total state size for indefinite streams
          if (next.length > maxBufferSize) {
            const overflow = next.length - maxBufferSize;
            onOverflowRef.current?.(overflow);
            return next.slice(overflow);
          }
          return next;
        });
      }
      rafRef.current = requestAnimationFrame(flush);
    };
    rafRef.current = requestAnimationFrame(flush);
  }, [maxBufferSize]);

  useEffect(() => {
    if (transport !== 'sse') return;

    const es = new EventSource(url);
    sourceRef.current = es;

    es.onopen = () => setStatus('open');

    es.onmessage = (event) => {
      try {
        const parsed = parseRef.current(event.data);
        onMessageRef.current?.(parsed);
        bufferRef.current.push(parsed);

        // Backpressure: if buffer grows too large between frames,
        // trim oldest entries
        if (bufferRef.current.length > maxBufferSize) {
          const dropped = bufferRef.current.length - maxBufferSize;
          bufferRef.current = bufferRef.current.slice(dropped);
          onOverflowRef.current?.(dropped);
        }
      } catch (e) {
        console.error('Parse error in SSE message:', e);
      }
    };

    es.onerror = (e) => {
      setError(e);
      setStatus('error');
    };

    startFlushLoop();

    return () => {
      es.close();
      sourceRef.current = null;
      cancelAnimationFrame(rafRef.current);
      setStatus('closed');
    };
  }, [url, transport, maxBufferSize, startFlushLoop]);

  const close = useCallback(() => {
    sourceRef.current?.close();
    cancelAnimationFrame(rafRef.current);
    setStatus('closed');
  }, []);

  return { data, status, error, close };
}

The buffer lives in bufferRef.current, a plain array that React knows nothing about. The RAF loop checks it every frame, and if anything's there, it flushes everything into state in one setData call, then clears the buffer. React sees at most one state update per animation frame, regardless of whether 1 or 50 messages arrived since the last frame.

Handling Reconnection and Backpressure

SSE has built-in reconnection: if the connection drops, the browser's EventSource implementation automatically reconnects. The server can control the retry delay by sending a retry: field in the event stream (that's part of the SSE protocol defined in the HTML Living Standard, not an HTTP header). For error scenarios that aren't transient, you'll want exponential backoff, which means closing the native EventSource and managing reconnection yourself with increasing delays.

One important limitation: EventSource cannot set arbitrary request headers. Authentication typically requires cookies (using the withCredentials option) or tokenized URLs with query parameters. If you need custom headers like Authorization: Bearer, you'll need the Fetch API with a readable stream instead of EventSource, or switch to the WebSocket transport.

The maxBufferSize option handles backpressure. If messages arrive faster than the RAF loop can flush them (unlikely at 60Hz, but possible under heavy tab throttling or on low-end devices), the buffer trims the oldest entries and fires onOverflow so the consumer can log or alert.

Extending to WebSockets

WebSocket Transport Layer

The WebSocket transport slots into the same hook structure, sharing the identical buffer and RAF flush mechanism. The key differences: WebSocket doesn't auto-reconnect (you build that yourself), the browser WebSocket API doesn't expose protocol-level ping/pong frames to JavaScript (heartbeats must be application-level), and you need to handle JSON.parse failures gracefully since binary frames and malformed messages are more common:

// WebSocket transport branch — same hook, different connection.
// This effect lives alongside the SSE effect inside useServerStream.
// It shares bufferRef, rafRef, parseRef, onMessageRef, onOverflowRef,
// and startFlushLoop from the hook body shown above.

useEffect(() => {
  if (transport !== 'ws') return;

  let ws: WebSocket;
  let heartbeatTimer: ReturnType<typeof setInterval>;
  let reconnectAttempts = 0;
  const maxReconnectDelay = 30_000;
  let intentionalClose = false;

  function connect() {
    ws = new WebSocket(url);
    // Default binaryType is 'blob'; set to 'arraybuffer' for binary protocols.
    // For JSON text-frame protocols this line can be omitted — text frames
    // always arrive as strings regardless of binaryType.

    ws.onopen = () => {
      setStatus('open');
      setError(null);
      reconnectAttempts = 0;

      // Application-level heartbeat (browser WS API has no ping())
      heartbeatTimer = setInterval(() => {
        if (ws.readyState === WebSocket.OPEN) {
          ws.send(JSON.stringify({ type: 'ping' }));
        }
      }, 30_000);
    };

    ws.onmessage = (event) => {
      try {
        const raw =
          typeof event.data === 'string'
            ? event.data
            : new TextDecoder().decode(event.data as ArrayBuffer);
        const parsed = parseRef.current(raw);
        // Skip heartbeat responses
        if ((parsed as any)?.type === 'pong') return;

        onMessageRef.current?.(parsed);
        bufferRef.current.push(parsed);

        if (bufferRef.current.length > maxBufferSize) {
          const dropped = bufferRef.current.length - maxBufferSize;
          bufferRef.current = bufferRef.current.slice(dropped);
          onOverflowRef.current?.(dropped);
        }
      } catch (e) {
        console.error('Parse error in WS message:', e);
      }
    };

    ws.onerror = (e) => {
      setError(e as Event);
      setStatus('error');
    };

    ws.onclose = () => {
      clearInterval(heartbeatTimer);
      if (intentionalClose) {
        setStatus('closed');
        return;
      }
      setStatus('closed');
      // Exponential backoff reconnection
      const delay = Math.min(1000 * 2 ** reconnectAttempts, maxReconnectDelay);
      reconnectAttempts++;
      setTimeout(connect, delay);
    };
  }

  connect();
  startFlushLoop();

  return () => {
    intentionalClose = true;
    clearInterval(heartbeatTimer);
    ws.close();
    cancelAnimationFrame(rafRef.current);
    setStatus('closed');
  };
}, [url, transport, maxBufferSize, startFlushLoop]);

Notice that ws.onmessage pushes to the same bufferRef the SSE transport uses. The RAF flush loop doesn't know or care which transport filled the buffer.

The default binaryType for a new WebSocket is 'blob', not 'text'. Setting it to 'blob' or 'arraybuffer' controls whether event.data arrives as a Blob, ArrayBuffer, or string (strings always show up as strings regardless of binaryType; the property only affects binary frames). For JSON-based protocols where the server sends text frames, event.data will already be a string. For binary protocols (e.g., Protocol Buffers), set binaryType = 'arraybuffer' and adjust the parse function accordingly.

Also worth knowing: ws.bufferedAmount is a read-only property that tells you how many bytes are queued for sending. Less relevant for a read-heavy streaming scenario, but useful if you're also sending data back to the server and need to detect backpressure on the outbound side.

Unified Transport Abstraction

Both transports share the buffer, the RAF loop, the state declarations, and the public API. The transport option just selects which connection logic runs in the effect:

function useServerStream<T = string>(
  url: string,
  options: UseServerStreamOptions<T>
): UseServerStreamReturn<T> {
  // ... shared state, refs, and flush loop (from SSE example above)

  // SSE transport effect
  useEffect(() => {
    if (options.transport !== 'sse') return;
    // ... SSE connection logic
  }, [/* deps */]);

  // WebSocket transport effect
  useEffect(() => {
    if (options.transport !== 'ws') return;
    // ... WebSocket connection logic
  }, [/* deps */]);

  return { data, status, error, close };
}

You could extract the transport-specific logic into separate modules (createSSETransport, createWSTransport) using a factory pattern, each returning { connect, disconnect } functions that accept a buffer ref. That keeps the hook body focused on React concerns while the transport modules deal with protocol details. For most applications, the conditional-effect approach above is simpler and good enough.

Controlling What Re-renders: Component-Level Strategies

Memoization That Actually Matters

Batching reduces how often React renders. You also need to minimize the work done per render. React.memo with a custom comparator is the primary tool. The comparator receives previous and next props and returns true if the component should skip re-rendering:

import React, { useMemo } from 'react';

interface TickerRowProps {
  symbol: string;
  price: number;
  volume: number;
  timestamp: number;
}

const TickerRow = React.memo(
  function TickerRow({ symbol, price, volume }: TickerRowProps) {
    const formattedPrice = useMemo(
      () => price.toLocaleString('en-US', { style: 'currency', currency: 'USD' }),
      [price]
    );

    return (
      <tr>
        <td>{symbol}</td>
        <td>{formattedPrice}</td>
        <td>{volume.toLocaleString()}</td>
      </tr>
    );
  },
  (prev, next) => {
    // Only re-render if price or symbol changed.
    // Ignore timestamp and volume churn.
    return prev.symbol === next.symbol && prev.price === next.price;
  }
);

The useMemo on formattedPrice makes sure the formatted string only gets recomputed when the raw price changes. Without it, toLocaleString runs on every render, and the child component receives a new string reference each time, defeating any downstream memo boundaries.

This approach falls apart when every field in your props matters and changes frequently. The comparator provides no savings in that case and just adds overhead. Use memoization surgically on components that receive the most data churn but only display a subset of it.

Virtualizing Long Streams

For unbounded streams like chat histories, log tails, or LLM output, the DOM becomes the bottleneck long before React reconciliation does. A list of 10,000 messages means 10,000 DOM nodes, each eating memory and slowing layout calculations.

@tanstack/react-virtual (or react-window if you want a lighter API) fixes this by only mounting DOM nodes for visible items. Here's how it integrates with useServerStream:

import { useRef, useEffect } from 'react';
import { useVirtualizer } from '@tanstack/react-virtual';

function StreamingMessageList({ url }: { url: string }) {
  const { data: messages, status } = useServerStream<string>(url, {
    transport: 'sse',
  });

  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: messages.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 40, // estimated row height in px
    overscan: 5,            // render 5 extra items above/below viewport
  });

  // Auto-scroll to bottom on new messages
  useEffect(() => {
    if (messages.length > 0) {
      virtualizer.scrollToIndex(messages.length - 1, { align: 'end' });
    }
  }, [messages.length, virtualizer]);

  return (
    <div ref={parentRef} style={{ height: '500px', overflow: 'auto' }}>
      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${virtualRow.start}px)`,
              width: '100%',
            }}
          >
            {messages[virtualRow.index]}
          </div>
        ))}
      </div>
    </div>
  );
}

The state array can grow to thousands of entries, but the DOM only ever contains the visible subset plus a small overscan buffer. I've run this pattern with 50,000+ items without any perceptible scroll jank on mid-range hardware.

When to Skip React State Entirely

For ultra-high-frequency visual updates (a single price value updating 60+ times per second), even one setState per frame is overkill. Write directly to the DOM via a ref:

import { useRef, useEffect } from 'react';

function FastPriceTicker({ url, symbol }: { url: string; symbol: string }) {
  const priceRef = useRef<HTMLSpanElement>(null);

  useEffect(() => {
    const ws = new WebSocket(url);

    ws.onmessage = (event) => {
      const { price } = JSON.parse(event.data);
      // Direct DOM mutation — React never re-renders
      if (priceRef.current) {
        priceRef.current.textContent = `$${price.toFixed(2)}`;
      }
    };

    return () => ws.close();
  }, [url]);

  return (
    <span>
      {symbol}: <span ref={priceRef}>--</span>
    </span>
  );
}

This bypasses React's render cycle completely. The component renders once on mount and never again. The onMessage callback in useServerStream enables this same pattern: use it for updates that are purely visual and don't need to participate in React's state tree. It breaks down when other components need to react to the same data, or when you need React's reconciliation for conditional rendering logic. It's an escape hatch, not a default.

This bypasses React's render cycle completely. The component renders once on mount and never again.

Putting It All Together: LLM Token Stream Demo

Full Working Example

Here's a minimal ChatGPT-style streaming UI that pulls everything together. The backend sends SSE tokens at variable rates. The frontend buffers them, renders tokens into a growing paragraph, and virtualizes the message history:

import React, { useState, useRef, useEffect, useMemo } from 'react';
import { useVirtualizer } from '@tanstack/react-virtual';

// Requires useServerStream and its associated types defined earlier in this article.

// Types
interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  complete: boolean;
}

// Streaming message component — displays tokens as they arrive
const StreamingMessage = React.memo(function StreamingMessage({
  message,
}: {
  message: ChatMessage;
}) {
  return (
    <div className={`message ${message.role}`}>
      <strong>{message.role}:</strong>
      <p>{message.content}{!message.complete && <span className="cursor">▊</span>}</p>
    </div>
  );
});

// Main chat UI
function ChatApp() {
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const [input, setInput] = useState('');
  const [streamUrl, setStreamUrl] = useState<string | null>(null);
  const parentRef = useRef<HTMLDivElement>(null);

  // Stream tokens for the current assistant response.
  // Only active when streamUrl is set (after the user submits a prompt).
  const { data: tokens, status } = useServerStream<string>(
    streamUrl ?? '',
    {
      transport: 'sse',
      parse: (raw) => JSON.parse(raw).token,
    }
  );

  // Aggregate tokens into the current assistant message
  const currentContent = useMemo(() => tokens.join(''), [tokens]);

  const allMessages = useMemo(() => {
    if (!streamUrl || tokens.length === 0) return messages;
    return [
      ...messages,
      {
        id: 'streaming',
        role: 'assistant' as const,
        content: currentContent,
        complete: status === 'closed',
      },
    ];
  }, [messages, streamUrl, currentContent, status, tokens.length]);

  // Virtualize message list
  const virtualizer = useVirtualizer({
    count: allMessages.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 80,
    overscan: 3,
  });

  useEffect(() => {
    if (allMessages.length > 0) {
      virtualizer.scrollToIndex(allMessages.length - 1, { align: 'end' });
    }
  }, [allMessages.length, virtualizer]);

  const handleSubmit = () => {
    if (!input.trim()) return;
    setMessages((prev) => [
      ...prev,
      { id: crypto.randomUUID(), role: 'user', content: input, complete: true },
    ]);
    setStreamUrl(`/api/chat/stream?prompt=${encodeURIComponent(input)}`);
    setInput('');
  };

  return (
    <div className="chat-container">
      <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
        <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
          {virtualizer.getVirtualItems().map((row) => (
            <div
              key={row.key}
              style={{
                position: 'absolute',
                top: 0,
                transform: `translateY(${row.start}px)`,
                width: '100%',
              }}
            >
              <StreamingMessage message={allMessages[row.index]} />
            </div>
          ))}
        </div>
      </div>
      <div>
        <input value={input} onChange={(e) => setInput(e.target.value)} />
        <button onClick={handleSubmit}>Send</button>
      </div>
    </div>
  );
}

Performance Comparison: Before vs. After

I tested both approaches on a production React 18.3 build (StrictMode off) in Chrome on an M2 MacBook Pro. The test harness sent synthetic SSE tokens at controlled rates, and I captured metrics using the React Profiler component's onRender callback (which reports actualDuration and commitTime for each render) alongside Chrome's Performance panel.

I expected the RAF-batched approach to reduce render frequency proportionally, but the commit time improvement was even bigger than I anticipated. Fewer renders meant React could skip diffing unchanged subtrees entirely, compounding the savings.

The "12 to 16 renders/sec" number reflects that RAF fires at up to 60Hz on a standard display, but the flush loop skips frames where the buffer is empty. The render count stays flat regardless of message rate because the buffer absorbs all variation between frames.

Production Hardening Checklist

Error Boundaries and Graceful Degradation

Wrap streaming components in a React error boundary. Error boundaries must be class components using static getDerivedStateFromError and/or componentDidCatch. One thing people miss: error boundaries catch errors during rendering and lifecycle methods only. They do not catch errors in async callbacks like onmessage. Handle those with try/catch in the hook itself (as shown in the code examples above).

For transport failures, build a fallback chain: try WebSocket first, fall back to SSE, and if both fail, degrade to polling. The useServerStream hook's status and error values give the consumer enough information to trigger fallback logic.

Memory Management

For indefinite streams (chat logs, system monitors), cap the state array length. The maxBufferSize option handles this in the hook, but also think about pruning old messages in the UI component. A leaked EventSource or WebSocket connection is the most common production bug in streaming UIs. Under React 18 StrictMode in development, effects mount, unmount, and remount, which will surface cleanup issues early. Make sure your cleanup function closes the connection and cancels the RAF loop unconditionally.

Testing the Hook

Mock EventSource and WebSocket in your tests. With Vitest, use vi.useFakeTimers() to control time progression. RAF mocking requires a custom stub since vi.useFakeTimers covers setTimeout/setInterval but not requestAnimationFrame by default:

// Vitest test helper for mocking requestAnimationFrame
let rafCallbacks: Array<FrameRequestCallback> = [];
let rafIdCounter = 0;

beforeEach(() => {
  rafCallbacks = [];
  rafIdCounter = 0;

  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
    rafCallbacks.push(cb);
    return ++rafIdCounter;
  });

  vi.stubGlobal('cancelAnimationFrame', (id: number) => {
    // In this simple stub, we clear all callbacks.
    // A more robust version would track by id.
    rafCallbacks = [];
  });
});

afterEach(() => {
  vi.unstubAllGlobals();
});

// In your test: flush one frame
function flushRAF() {
  const cbs = [...rafCallbacks];
  rafCallbacks = [];
  cbs.forEach((cb) => cb(performance.now()));
}

This lets you push messages into a mock WebSocket, advance a frame, and assert that the hook's state contains exactly the buffered batch.

Key Takeaways

Never call setState directly from a stream callback. Buffer incoming messages in a mutable ref and flush them on a requestAnimationFrame cadence. This aligns your updates to the display refresh rate (60Hz, 90Hz, or 120Hz depending on the device) and collapses any number of incoming messages into a single render per frame.

Never call setState directly from a stream callback. Buffer incoming messages in a mutable ref and flush them on a requestAnimationFrame cadence.

Memoize and virtualize the render tree so each batched update touches minimal DOM. React.memo with custom comparators prevents unnecessary child renders; @tanstack/react-virtual keeps DOM node count constant regardless of data size.

The useServerStream hook wraps all of this in a clean, reusable API with a single transport toggle between SSE and WebSocket. For cases where even one render per frame is too much, the onMessage escape hatch lets you bypass React entirely and write straight to the DOM.

Look into useSyncExternalStore if your buffer logic grows complex or needs to be shared across multiple components. It's React 18's official primitive for exactly this kind of external data subscription.

The complete hook source works as a standalone module you can drop into any project. The patterns here apply anywhere data arrives faster than users can perceive: AI chat, trading platforms, multiplayer cursors, IoT dashboards, and log streaming interfaces.