broadcastQueryClient (실험적)

매우 중요: 이 유틸리티는 현재 실험 단계입니다. 이는 마이너 및 패치 릴리스에서 호환성을 깨뜨리는 변경 사항이 발생한다는 의미입니다. 위험을 감수하고 사용하세요. 실험 단계에서 프로덕션 환경에 이를 사용하기로 했다면 예기치 않은 호환성 문제를 방지하도록 버전을 패치 수준 버전으로 고정하세요.

broadcastQueryClient는 동일한 출처의 브라우저 탭/창 간에 queryClient의 상태를 브로드캐스트하고 동기화하는 유틸리티입니다.

설치

이 유틸리티는 별도 패키지로 제공되며 '@tanstack/query-broadcast-client-experimental' import를 통해 사용할 수 있습니다.

사용법

broadcastQueryClient 함수를 import하고 QueryClient 인스턴스를 전달한 다음, 선택적으로 broadcastChannel을 설정합니다.

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

const queryClient = new QueryClient()

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

API

broadcastQueryClient

이 함수에 QueryClient 인스턴스를 전달하고, 선택적으로 broadcastChannel도 전달합니다.

broadcastQueryClient({ queryClient, broadcastChannel })

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
}

기본 옵션은 다음과 같습니다:

{
  broadcastChannel = 'tanstack-query',
}

브로드캐스트 오류 처리

캐시에 구조화 복제가 불가능한 값(예: ReadableStream(Response.body, 스트리밍 API 또는 AI SDK에서 비롯됨), File, 함수 또는 Vue reactive 같은 프레임워크 프록시)이 포함될 수 있다면, 기본 BroadcastChannel.postMessage 호출은 해당 쿼리에 대해 거부됩니다. 해당 쿼리의 탭 간 동기화는 건너뛰며, 캐시의 나머지 부분은 계속 정상적으로 브로드캐스트됩니다.

기본적으로 실패가 절대 조용히 넘어가지 않도록 개발 환경에서는 console.warn이 출력됩니다. 실패를 자체 오류 추적기로 전달하려면 onBroadcastError를 제공합니다:

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 },
    })
  },
})