Real-Time Updates

Concept of the skill

Browser freshness has four primitives: a source of change, a delivery channel, a browser cache or view state, and a freshness contract shown to the user.

Coverage

• Browser freshness decisions for dashboards, feeds, progress panels, notifications, and views that can become stale after initial render.
• Transport selection among adaptive polling, Server-Sent Events, and bidirectional sockets.
• Webhook-to-UI propagation at a pattern level: external change, server state, browser notification, and catch-up fetch.
• Client cache invalidation and refetch orchestration after a live notification.
• Optimistic update safety: when to apply immediately, when to wait, and how to roll back.
• Stale-data communication: timestamps, stale badges, connection status, and non-disruptive refresh prompts.
• Reconnect and missed-update recovery: last seen version, cursor, timestamp, or sequence number.
• Subscription ownership: one shared subscription per resource instead of independent polling loops in every component.

Philosophy of the skill

Stale data without a freshness signal is a false statement. A dashboard that fetched once and never says so teaches the user to trust numbers, statuses, or notifications that may already be outdated.

Real-time design is not the same as choosing the flashiest transport. Polling can be the best design when data changes slowly or hosting cannot keep long connections open. Server-Sent Events are the default for one-way server-to-browser updates. Bidirectional sockets are justified only when the browser must also send frequent low-latency messages over the same channel. The transport is a consequence of the freshness contract, not the starting point.

The strongest systems also keep control with the user. If an update would reorder a table, interrupt a form, clear a selection, or move the scroll position, the interface should announce that new data is available instead of silently replacing the view.

A browser update message should usually be treated as a freshness signal, not as the entire source of truth. Push can tell the browser what changed; the browser still reconciles from durable server state or a cache that is invalidated and refetched.

Freshness Contract First

Before choosing a transport, define the user-visible freshness contract.

Transport Decision Matrix

Decision Rule

Use this order:

1. If the browser only needs periodic latest state and seconds of delay are acceptable, use adaptive polling.
2. If the server needs to push one-way updates and long connections are supported, use Server-Sent Events.
3. If the browser must send frequent low-latency messages over the same live channel, use a bidirectional socket.
4. If the selected transport cannot replay or recover missed updates, add a catch-up fetch after reconnect.

Do not choose a bidirectional socket only because the feature is called "real-time." Directionality and recovery requirements decide.

Webhook-To-UI Propagation

An external change does not automatically become a browser update. Treat it as a four-stage pipeline.

External change
  -> Server receives and validates the change
  -> Durable state is updated
  -> Browser freshness channel is notified or polled
  -> Browser reconciles from authoritative state

The browser should usually reconcile from authoritative server state rather than trusting the push message as the full truth. A push message can be small: resource type, resource ID, version, and timestamp. The browser then decides whether to refetch a row, a page, or a summary.

Adaptive Polling

Polling is not a failure. Poor polling is the failure.

Use adaptive polling when persistent connections are unnecessary or unavailable:

• Poll faster while the tab is visible and the view is active.
• Poll slower or pause when the tab is hidden.
• Use conditional requests, versions, cursors, or updated-at filters when available.
• Centralize polling per resource so multiple components share one result.
• Surface stale state when polling fails or data ages beyond the threshold.

type PollingState<T> = {
  data: T | null;
  lastFetchedAt: number | null;
  isStale: boolean;
  error: Error | null;
};

function choosePollInterval(isVisible: boolean, hasRecentActivity: boolean) {
  if (!isVisible) return 60_000;
  if (hasRecentActivity) return 5_000;
  return 20_000;
}

Avoid putting document.hidden directly in a React dependency array. Track visibility through a visibilitychange listener or a shared visibility hook, then derive the interval from that state.

Server-Sent Events

Use SSE for one-way server-to-browser updates such as status feeds, progress, notification counts, or dashboard invalidation messages.

Minimum SSE contract:

• Event type: what kind of update this is.
• Event ID or version: what the browser can use to resume or catch up.
• Data payload: small enough to process quickly.
• Heartbeat or keepalive: keeps intermediaries from closing quiet streams.
• Abort cleanup: closes timers, subscriptions, and handles when the browser disconnects.

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

  const stream = new ReadableStream({
    start(controller) {
      const heartbeat = setInterval(() => {
        controller.enqueue(encoder.encode(': keepalive\n\n'));
      }, 25_000);

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

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-store',
    },
  });
}

SSE has built-in reconnect, but that does not guarantee the browser received every update. Use Last-Event-ID, a version field, or a timestamp to fetch missed state after reconnect.

On the browser side, keep the live stream small and treat it as an invalidation signal. Store the last event ID, show connection state, and reconcile from durable server state after reconnect.

let lastEventId: string | null = null;

function subscribeToOrderUpdates(refetchSince: (id: string | null) => Promise<void>) {
  const events = new EventSource('/api/order-events');

  events.onopen = async () => {
    setConnectionState('live');
    await refetchSince(lastEventId);
  };

  events.addEventListener('order.updated', async (event) => {
    lastEventId = event.lastEventId || JSON.parse(event.data).version;
    invalidateOrderCache(JSON.parse(event.data).orderId);
  });

  events.onerror = () => {
    setConnectionState('reconnecting');
  };

  return () => events.close();
}

If the server cannot replay from Last-Event-ID, use the remembered event ID, version, cursor, or timestamp as a catch-up query parameter on reconnect. If even that is unavailable, perform a full refetch before marking the view live again.

Bidirectional Sockets

Use a bidirectional socket only when the browser must send frequent low-latency messages while also receiving server updates.

Good fits:

• Presence and live cursors.
• Collaborative editing.
• Multiplayer or live control surfaces.
• Chat-like interactions where both sides can speak at any time.

Poor fits:

• Notification badges.
• Dashboard invalidation.
• Progress updates.
• Occasional browser actions that can use ordinary HTTP requests.

If a bidirectional socket is justified, verify heartbeat, reconnect, backoff, authorization, room cleanup, message envelope, and backpressure with streaming-architecture or a dedicated socket skill in the consuming environment.

Optimistic Updates

Optimistic updates make the interface feel instant, but they are safe only when the action is reversible and the speculative state cannot mislead.

Every optimistic update needs:

• Previous state for rollback.
• Pending affordance so the user knows confirmation is not final yet.
• Failure message with recovery.
• Reconciliation with server state after success.

Stale Data Indicators

Every live view should communicate freshness at the level of precision the user needs.

Auto-refresh is safe for small, non-interactive counters. It is not safe for tables, forms, selected lists, or scroll-sensitive surfaces unless the update preserves the user's position and selection.

Reconnect And Catch-Up

Persistent connections drop during deploys, network changes, sleep/wake cycles, and proxy timeouts. Reconnect is incomplete without catch-up.

Use this recovery sequence:

1. Detect disconnect and show a non-blocking connection status.
2. Reconnect with exponential backoff and jitter.
3. Send or remember the last seen event ID, version, cursor, or timestamp.
4. Fetch missed state before declaring the view current.
5. Deduplicate updates that arrive both through catch-up and the live channel.
6. Clear the warning only after authoritative state has been reconciled.

If the system cannot determine what was missed, perform a full refetch and say the view was refreshed, not replayed.

Subscription Ownership

Do not let every component open its own connection or polling loop for the same resource.

Better ownership patterns:

• One route-level subscription that distributes state through context or a shared store.
• One query-cache subscription that invalidates resource keys.
• One server stream per browser view, multiplexing update types in the event payload.
• One polling coordinator that batches interested components.

Central ownership reduces duplicate requests, connection count, inconsistent stale indicators, and race conditions between components.

Verification

After applying this skill, verify:

• [ ] The freshness contract is explicit: acceptable age, user disruption rules, and recovery behavior are named.
• [ ] The transport choice matches directionality, hosting limits, and recovery needs.
• [ ] Server-to-browser-only flows do not default to bidirectional sockets without a specific bidirectional requirement.
• [ ] Persistent connections have reconnect, backoff, visible status, cleanup on disconnect, and catch-up from last seen state.
• [ ] Polling adapts to visibility or activity and is centralized per shared resource.
• [ ] Every stale or live claim has a timestamp, status badge, or equivalent freshness indicator.
• [ ] Optimistic updates include pending state, rollback, failure recovery, and server reconciliation.
• [ ] Auto-refresh does not disrupt active typing, selection, scrolling, or filtering.
• [ ] Missed updates are deduplicated after reconnect or full refetch.

Do NOT Use When

Anti-Patterns