fix(react-query): hydrate disabled query shells in HydrationBoundary

Author: byungsker

.changeset/fix-hydration-boundary-disabled-shell.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/react-query': patch
+---
+
+Fix `HydrationBoundary` deferring hydration for disabled query shells

packages/query-core/src/__tests__/hydration.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { QueryClient } from '../queryClient'
 import { QueryCache } from '../queryCache'
+import { QueryObserver } from '../queryObserver'
 import { dehydrate, hydrate } from '../hydration'
 import { MutationCache } from '../mutationCache'
 import { executeMutation, mockOnlineManagerIsOnline } from './utils'
@@ -960,6 +961,47 @@ describe('dehydration and rehydration', () => {
     })
   })
 
+  test('should hydrate over an existing disabled query shell', async () => {
+    const key = queryKey()
+
+    const prefetchClient = new QueryClient()
+    const prefetchPromise = prefetchClient.prefetchQuery({
+      queryKey: key,
+      queryFn: () => sleep(10).then(() => 'prefetched'),
+    })
+    await vi.advanceTimersByTimeAsync(10)
+    await prefetchPromise
+    const dehydrated = dehydrate(prefetchClient)
+
+    const hydrationClient = new QueryClient()
+    const observer = new QueryObserver(hydrationClient, {
+      queryKey: key,
+      queryFn: () => Promise.resolve('client'),
+      enabled: false,
+    })
+    const unsubscribe = observer.subscribe(vi.fn())
+
+    const disabledShellQuery = hydrationClient.getQueryCache().find({ queryKey: key })
+
+    expect(disabledShellQuery?.state).toMatchObject({
+      data: undefined,
+      fetchStatus: 'idle',
+      status: 'pending',
+    })
+    expect(disabledShellQuery?.isDisabled()).toBe(true)
+
+    hydrate(hydrationClient, dehydrated)
+
+    expect(hydrationClient.getQueryCache().find({ queryKey: key })?.state).toMatchObject({
+      data: 'prefetched',
+      status: 'success',
+    })
+
+    unsubscribe()
+    prefetchClient.clear()
+    hydrationClient.clear()
+  })
+
   test('should transform promise result', async () => {
     const key = queryKey()
     const queryClient = new QueryClient({

packages/react-query/src/HydrationBoundary.tsx

@@ -82,8 +82,17 @@ export const HydrationBoundary = ({
                 dehydratedQuery.dehydratedAt >
                   existingQuery.state.dataUpdatedAt)
 
+            const canHydrateExistingInRender =
+              existingQuery.state.fetchStatus === 'idle' &&
+              (existingQuery.state.data === undefined ||
+                existingQuery.isDisabled())
+
             if (hydrationIsNewer) {
-              existingQueries.push(dehydratedQuery)
+              if (canHydrateExistingInRender) {
+                newQueries.push(dehydratedQuery)
+              } else {
+                existingQueries.push(dehydratedQuery)
+              }
             }
           }
         }

packages/react-query/src/__tests__/HydrationBoundary.test.tsx

@@ -9,7 +9,9 @@ import {
   QueryClientProvider,
   dehydrate,
   useQuery,
+  useSuspenseQuery,
 } from '..'
+import { renderWithClient } from './utils'
 import type { hydrate } from '@tanstack/query-core'
 
 describe('React hydration', () => {
@@ -511,6 +513,59 @@ describe('React hydration', () => {
     queryClient.clear()
   })
 
+  test('should hydrate an existing disabled query before a nested suspense query with the same key mounts', async () => {
+    const prefetchedData = ['prefetched']
+    const clientQueryFn = vi.fn(() => sleep(20).then(() => ['client']))
+    const queryClient = new QueryClient()
+
+    const prefetchClient = new QueryClient()
+    const prefetchPromise = prefetchClient.prefetchQuery({
+      queryKey: ['string'],
+      queryFn: () => sleep(10).then(() => prefetchedData),
+    })
+    await vi.advanceTimersByTimeAsync(10)
+    await prefetchPromise
+    const dehydratedState = dehydrate(prefetchClient)
+    prefetchClient.clear()
+
+    function Header() {
+      useQuery({
+        queryKey: ['string'],
+        queryFn: clientQueryFn,
+        enabled: false,
+      })
+      return null
+    }
+
+    function Child() {
+      useSuspenseQuery({
+        queryKey: ['string'],
+        queryFn: clientQueryFn,
+      })
+      return null
+    }
+
+    renderWithClient(
+      queryClient,
+      <>
+        <Header />
+        <React.Suspense fallback="loading">
+          <HydrationBoundary state={dehydratedState}>
+            <Child />
+          </HydrationBoundary>
+        </React.Suspense>
+      </>,
+    )
+
+    expect(queryClient.getQueryCache().find({ queryKey: ['string'] })?.state).toMatchObject({
+      data: prefetchedData,
+      status: 'success',
+    })
+    expect(clientQueryFn).toHaveBeenCalledTimes(0)
+
+    queryClient.clear()
+  })
+
   test('should not refetch when query has staleTime set to Infinity', async () => {
     const queryFn = vi.fn()
     const queryClient = new QueryClient()