본문으로 건너뛰기

하이드레이션

dehydrate​

dehydrate는 나중에 HydrationBoundary 또는 hydrate로 하이드레이션할 수 있는 cache의 고정된 표현을 생성합니다. 이는 프리페치한 쿼리를 서버에서 클라이언트로 전달하거나 쿼리를 localStorage 또는 기타 영구 저장 위치에 영구 저장하는 데 유용합니다. 기본적으로 현재 성공한 쿼리만 포함합니다.

import { dehydrate } from '@tanstack/react-query'

const dehydratedState = dehydrate(queryClient, {
  shouldDehydrateQuery,
  shouldDehydrateMutation,
})

옵션

  • client: QueryClient
    • Required
    • 디하이드레이션해야 하는 queryClient
  • options: DehydrateOptions
    • 선택 사항
    • shouldDehydrateMutation: (mutation: Mutation) => boolean
      • 선택 사항
      • 뮤테이션을 디하이드레이션할지 여부입니다.
      • 캐시의 각 뮤테이션에 대해 함수가 호출됩니다
        • 이 뮤테이션을 디하이드레이션에 포함하려면 true를 반환하고, 그렇지 않으면 false를 반환합니다
      • 기본적으로 일시 중지된 뮤테이션만 포함합니다
      • 기본 동작을 유지하면서 함수를 확장하려면 return 문에 defaultShouldDehydrateMutation을 import하고 실행합니다
    • shouldDehydrateQuery: (query: Query) => boolean
      • 선택 사항
      • 쿼리를 디하이드레이션할지 여부입니다.
      • 이 함수는 캐시의 각 쿼리에 대해 호출됩니다
        • 이 쿼리를 디하이드레이션에 포함하려면 true를 반환하고, 그렇지 않으면 false를 반환하세요
      • 기본적으로 성공한 쿼리만 포함합니다
      • 기본 동작을 유지하면서 함수를 확장하려면 return 문에 defaultShouldDehydrateQuery를 import하고 실행합니다
    • serializeData?: (data: any) => any 디하이드레이션 중 데이터를 변환(직렬화)하는 함수입니다.
    • shouldRedactErrors?: (error: unknown) => boolean
      • 선택 사항
      • 디하이드레이션 중 서버의 오류를 마스킹할지 여부입니다.
      • 이 함수는 캐시의 각 오류에 대해 호출됩니다
        • 이 오류를 숨기려면 true를 반환하고, 그렇지 않으면 false를 반환합니다
      • 기본적으로 모든 오류를 수정 처리합니다.

반환값

  • dehydratedState: DehydratedState
    • 여기에는 나중에 queryClient를 하이드레이션하는 데 필요한 모든 것이 포함됩니다
    • 이 응답의 정확한 형식에 의존해서는 안 됩니다. 이는 공개 API의 일부가 아니며 언제든지 변경될 수 있습니다.
    • 이 결과는 직렬화된 형태가 아니므로, 원한다면 직접 직렬화해야 합니다

제한 사항​

일부 저장소 시스템(예: 브라우저 Web Storage API)에서는 값을 JSON 직렬화할 수 있어야 합니다. JSON으로 자동 직렬화할 수 없는 값(예: Error 또는 undefined)을 디하이드레이션해야 한다면 직접 직렬화해야 합니다. 기본적으로 성공한 쿼리만 포함되므로 Errors도 포함하려면 shouldDehydrateQuery를 제공해야 합니다. 예:

// server
const state = dehydrate(client, { shouldDehydrateQuery: () => true }) // to also include Errors
const serializedState = mySerialize(state) // transform Error instances to objects

// client
const state = myDeserialize(serializedState) // transform objects back to Error instances
hydrate(client, state)

hydrate​

hydrate는 이전에 디하이드레이션된 상태를 cache에 추가합니다.

import { hydrate } from '@tanstack/react-query'

hydrate(queryClient, dehydratedState, options)

옵션

  • client: QueryClient
    • Required
    • 상태를 하이드레이션할 queryClient
  • dehydratedState: DehydratedState
    • Required
    • 클라이언트에 하이드레이션할 상태
  • options: HydrateOptions
    • 선택 사항
    • defaultOptions: DefaultOptions
      • 선택 사항
      • mutations: MutationOptions 하이드레이션된 뮤테이션에 사용할 기본 뮤테이션 옵션입니다.
      • queries: QueryOptions 하이드레이션된 쿼리에 사용할 기본 쿼리 옵션입니다.
      • deserializeData?: (data: any) => any 데이터를 캐시에 넣기 전에 변환(역직렬화)하는 함수입니다.
    • queryClient?: QueryClient
      • 사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 context의 항목이 사용됩니다.

제한 사항​

하이드레이션하려는 쿼리가 이미 queryCache에 존재하는 경우, hydrate는 데이터가 캐시에 있는 데이터보다 최신일 때만 이를 덮어씁니다. 그렇지 않으면 적용되지 않습니다.

HydrationBoundary​

HydrationBoundary는 이전에 디하이드레이션된 상태를 useQueryClient()가 반환할 queryClient에 추가합니다. 클라이언트에 이미 데이터가 있는 경우 새 쿼리는 업데이트 타임스탬프를 기준으로 지능적으로 병합됩니다.

import { HydrationBoundary } from '@tanstack/react-query'

function App() {
  return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
}

참고: queries만 HydrationBoundary를 사용하여 디하이드레이션할 수 있습니다.

옵션

  • state: DehydratedState
    • 하이드레이션할 상태
  • options: HydrateOptions
    • 선택 사항
    • defaultOptions: QueryOptions
      • 하이드레이션된 쿼리에 사용할 기본 쿼리 옵션입니다.
      • 참고: hydrate와 달리 여기서는 mutations를 설정할 수 없습니다.
  • queryClient?: QueryClient
    • 사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 context의 항목이 사용됩니다.