0
Fork 0
mirror of https://github.com/TanStack/query.git synced 2026-11-18 19:33:22 +00:00
query/docs/framework/react/plugins/broadcastQueryClient.md
n-satoshi061 3c79861ab1
fix(broadcast-client): handle unhandled postMessage rejections (#10771)
* fix(broadcast-client): handle unhandled postMessage rejections

Wrap channel.postMessage() calls in safePost() to catch DataCloneError
and similar failures that occur when query data contains non-cloneable
values (ReadableStream, Response, Vue reactive proxies, etc.).

Adds an optional onBroadcastError callback to BroadcastQueryClientOptions
so consumers can pipe errors to Sentry/Datadog. Falls back to console.warn
in development when the callback is not provided.

Fixes #10543

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(broadcast-client): guard against throwing onBroadcastError callback

Wrap onBroadcastError() in a try/catch so that if the callback itself
throws, the error does not escape as an unhandled rejection. Falls back
to console.warn in development when the callback throws.

Add a test asserting no unhandledRejection fires when onBroadcastError throws.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(broadcast-client): handle async onBroadcastError rejections

Support async onBroadcastError callbacks by calling .catch() on the
returned Promise, preventing unhandled rejections when the callback
rejects asynchronously.

Also extracts the console.warn fallback into warnBroadcastError to
deduplicate the warning logic.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(broadcast-client): use try/finally to ensure unhandledRejection listener cleanup

Prevents listener leaks into subsequent tests if an assertion throws
before process.off() is reached.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(broadcast-client): improve types, messages, and docs

- Export BroadcastErrorEvent interface with QueryKey typing so consumers
  can import the type directly
- Use discriminated union for internal BroadcastMessage (state only on
  updated) for more precise typing
- onBroadcastError now receives BroadcastErrorEvent (no internal state
  field) instead of the raw BroadcastMessage
- Differentiate dev warning messages: broadcast failures explain the
  structured-clone cause and consequence; onBroadcastError failures
  explicitly identify the hook as the source
- Remove warnBroadcastError helper in favour of context-specific inlined
  warn calls
- Fix duplicate queryClient.getQueryCache() call (use queryCache directly)
- Add JSDoc to all BroadcastQueryClientOptions fields
- Add onBroadcastError section to broadcastQueryClient docs with Sentry
  example

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(broadcast-client): assert warn message when onBroadcastError throws or rejects

Add two tests that verify the '[broadcastQueryClient] onBroadcastError
threw while handling...' console.warn message is emitted in development
when the onBroadcastError callback itself throws synchronously or rejects
asynchronously.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(broadcast-client): include state in 'added' broadcasts

The receiver's onmessage handler reads state for 'added' events to call
query.setState(state) and queryCache.build(..., state), but the sender
was not including state in the outbound message. This caused receiving
tabs to apply undefined state for newly added queries.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(broadcast-client): wrap warnSpy in try/finally to prevent spy leakage

If an assertion fails before mockRestore(), the console.warn spy would
leak into subsequent tests. Wrapping each spy block in try/finally
ensures restore always runs regardless of test outcome.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* ci: apply automated fixes

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Dominik Dorfmeister 🔮 <office@dorfmeister.cc>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-08-20 10:24:33 +02:00

3.3 KiB

id title
broadcastQueryClient broadcastQueryClient (Experimental)

VERY IMPORTANT: This utility is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Use at your own risk. If you choose to rely on this in production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breakages.

broadcastQueryClient is a utility for broadcasting and syncing the state of your queryClient between browser tabs/windows with the same origin.

Installation

This utility comes as a separate package and is available under the '@tanstack/query-broadcast-client-experimental' import.

Usage

Import the broadcastQueryClient function, and pass it your QueryClient instance, and optionally, set a broadcastChannel.

import { broadcastQueryClient } from '@tanstack/query-broadcast-client-experimental'

const queryClient = new QueryClient()

broadcastQueryClient({
  queryClient,
  broadcastChannel: 'my-app',
})

API

broadcastQueryClient

Pass this function a QueryClient instance and optionally, a broadcastChannel.

broadcastQueryClient({ queryClient, broadcastChannel })

Options

An object of options:

interface BroadcastQueryClientOptions {
  /** The QueryClient to sync */
  queryClient: QueryClient
  /** This is the unique channel name that will be used
   * to communicate between tabs and windows */
  broadcastChannel?: string
  /** Options for the BroadcastChannel API */
  options?: BroadcastChannelOptions
  /**
   * Called when a query event fails to broadcast to other tabs — most
   * commonly because the query's data, error, or key contains a value the
   * structured-clone algorithm cannot serialize (e.g. `ReadableStream`,
   * `File`, functions, Vue `reactive` proxies).
   *
   * If omitted, a `console.warn` is emitted in development so failures
   * are never entirely silent. May return a `Promise`; any rejection is
   * caught internally.
   */
  onBroadcastError?: (
    error: unknown,
    event: BroadcastErrorEvent,
  ) => void | Promise<void>
}

interface BroadcastErrorEvent {
  type: 'updated' | 'removed' | 'added'
  queryHash: string
  queryKey: QueryKey
}

The default options are:

{
  broadcastChannel = 'tanstack-query',
}

Handling broadcast errors

If your cache can hold values that are not structured-cloneable — such as ReadableStream (from Response.body, streaming APIs, or AI SDKs), File, functions, or framework proxies like Vue reactive — the underlying BroadcastChannel.postMessage call will reject for that query. Cross-tab sync is skipped for that query; the rest of the cache continues to broadcast normally.

By default, a console.warn is emitted in development so failures are never silent. Provide onBroadcastError to route failures to your own error tracker:

import * as Sentry from '@sentry/browser'
import { broadcastQueryClient } from '@tanstack/query-broadcast-client-experimental'

broadcastQueryClient({
  queryClient,
  broadcastChannel: 'my-app',
  onBroadcastError: (error, event) => {
    Sentry.captureException(error, {
      tags: { broadcastEvent: event.type },
      extra: { queryHash: event.queryHash, queryKey: event.queryKey },
    })
  },
})