Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

broadcastQueryClient.md

103 lines3.3 KB

1---
2id: broadcastQueryClient
3title: broadcastQueryClient (Experimental)
4---
5​
6> 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.
7​
8`broadcastQueryClient` is a utility for broadcasting and syncing the state of your queryClient between browser tabs/windows with the same origin.
9​
10## Installation
11​
12This utility comes as a separate package and is available under the `'@tanstack/query-broadcast-client-experimental'` import.
13​
14## Usage
15​
16Import the `broadcastQueryClient` function, and pass it your `QueryClient` instance, and optionally, set a `broadcastChannel`.
17​
18```tsx
19import { broadcastQueryClient } from '@tanstack/query-broadcast-client-experimental'
20​
21const queryClient = new QueryClient()
22​
23broadcastQueryClient({
24 queryClient,
25 broadcastChannel: 'my-app',
26})
27```
28​
29## API
30​
31### `broadcastQueryClient`
32​
33Pass this function a `QueryClient` instance and optionally, a `broadcastChannel`.
34​
35```tsx
36broadcastQueryClient({ queryClient, broadcastChannel })
37```
38​
39### `Options`
40​
41An object of options:
42​
43```tsx
44interface BroadcastQueryClientOptions {
45 /** The QueryClient to sync */
46 queryClient: QueryClient
47 /** This is the unique channel name that will be used
48 * to communicate between tabs and windows */
49 broadcastChannel?: string
50 /** Options for the BroadcastChannel API */
51 options?: BroadcastChannelOptions
52 /**
53 * Called when a query event fails to broadcast to other tabs β€” most
54 * commonly because the query's data, error, or key contains a value the
55 * structured-clone algorithm cannot serialize (e.g. `ReadableStream`,
56 * `File`, functions, Vue `reactive` proxies).
57 *
58 * If omitted, a `console.warn` is emitted in development so failures
59 * are never entirely silent. May return a `Promise`; any rejection is
60 * caught internally.
61 */
62 onBroadcastError?: (
63 error: unknown,
64 event: BroadcastErrorEvent,
65 ) => void | Promise<void>
67​
68interface BroadcastErrorEvent {
69 type: 'updated' | 'removed' | 'added'
70 queryHash: string
71 queryKey: QueryKey
73```
74​
75The default options are:
76​
77```tsx
79 broadcastChannel = 'tanstack-query',
81```
82​
83## Handling broadcast errors
84​
85If 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.
86​
87By default, a `console.warn` is emitted in development so failures are never silent. Provide `onBroadcastError` to route failures to your own error tracker:
88​
89```tsx
90import * as Sentry from '@sentry/browser'
91import { broadcastQueryClient } from '@tanstack/query-broadcast-client-experimental'
92​
93broadcastQueryClient({
94 queryClient,
95 broadcastChannel: 'my-app',
96 onBroadcastError: (error, event) => {
97 Sentry.captureException(error, {
98 tags: { broadcastEvent: event.type },
99 extra: { queryHash: event.queryHash, queryKey: event.queryKey },
100 })
101 },
102})
103```