broadcastQueryClient - experimental state

[jimbo0378]

Hi there! We're looking at using broadcastQueryClient for a small production feature. It’s been marked as experimental for quite a while, so I was wondering if there are any updates on its status. Aside from possible API changes, are there any reasons we should avoid using it in production?

[Felipeness]

I'd use it in production, yeah. The "experimental" label is about the plugin API surface potentially changing, not about the underlying tech being unstable.

Under the hood it's just BroadcastChannel — well-supported, no network overhead, purely tab-to-tab within the same origin. All it does is sync cache state (invalidations, data updates) across tabs. If the broadcast fails for whatever reason, each tab still has its own fully working cache. Worst case is slightly stale data until the next refetch, which is fine.

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

const queryClient = new QueryClient();

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

Two things to keep in mind though. Your query data needs to be serializable — no functions, Dates become strings, the usual postMessage constraints. And if you're caching large payloads (paginated lists with thousands of items), broadcasting every update can get heavy, so you might want to be selective about which queries participate.

There's also no conflict resolution if two tabs mutate the same resource at the same time — last write wins. For most apps that's totally fine, but worth knowing. And obviously skip it on the server (no BroadcastChannel in SSR).

Honestly, the abstraction is thin enough that the API is unlikely to change much. I wouldn't overthink the "experimental" tag here.