Prevent useQuery from skipping hydration

.changeset/moody-cities-stand.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/react-query': patch
+'@tanstack/query-core': patch
+---
+
+prevent registered useQueries from skipping hydration

packages/query-core/src/hydration.ts

@@ -217,6 +217,11 @@ export function hydrate(
       let query = queryCache.get(queryHash)
       const existingQueryIsPending = query?.state.status === 'pending'
       const existingQueryIsFetching = query?.state.fetchStatus === 'fetching'
+      const existingQueryIsUndefinedOrIsIdleUseQuery =
+        !query ||
+        (query.state.dataUpdatedAt === 0 &&
+          query.state.status === 'pending' &&
+          query.state.fetchStatus === 'idle')
 
       // Do not hydrate if an existing query exists with newer data
       if (query) {
@@ -262,8 +267,8 @@ export function hydrate(
 
       if (
         promise &&
-        !existingQueryIsPending &&
-        !existingQueryIsFetching &&
+        (existingQueryIsUndefinedOrIsIdleUseQuery ||
+          (!existingQueryIsPending && !existingQueryIsFetching)) &&
         // Only hydrate if dehydration is newer than any existing data,
         // this is always true for new queries
         (dehydratedAt === undefined || dehydratedAt > query.state.dataUpdatedAt)

packages/react-query/src/HydrationBoundary.tsx

@@ -68,9 +68,15 @@ export const HydrationBoundary = ({
         const existingQueries: DehydratedState['queries'] = []
         for (const dehydratedQuery of queries) {
           const existingQuery = queryCache.get(dehydratedQuery.queryHash)
+          const existingQueryIsIdleUseQuery =
+            existingQuery?.state.dataUpdatedAt === 0 &&
+            existingQuery.state.status === 'pending' &&
+            existingQuery.state.fetchStatus === 'idle'
 
           if (!existingQuery) {
             newQueries.push(dehydratedQuery)
+          } else if (existingQueryIsIdleUseQuery) {
+            newQueries.push(dehydratedQuery)
           } else {
             const hydrationIsNewer =
               dehydratedQuery.state.dataUpdatedAt >

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

@@ -7,8 +7,10 @@ import {
   HydrationBoundary,
   QueryClient,
   QueryClientProvider,
+  defaultShouldDehydrateQuery,
   dehydrate,
   useQuery,
+  useSuspenseQuery,
 } from '..'
 import type { hydrate } from '@tanstack/query-core'
 
@@ -481,6 +483,70 @@ describe('React hydration', () => {
     clientQueryClient.clear()
   })
 
+  test('should hydrate pending idle queries in render to avoid suspense refetches', async () => {
+    const queryKey = ['string'] as const
+
+    const makeQueryClient = () =>
+      new QueryClient({
+        defaultOptions: {
+          dehydrate: {
+            shouldDehydrateQuery: (query) =>
+              defaultShouldDehydrateQuery(query) ||
+              query.state.status === 'pending',
+            shouldRedactErrors: () => false,
+          },
+        },
+      })
+
+    const prefetchClient = makeQueryClient()
+    void prefetchClient.prefetchQuery({
+      queryKey,
+      queryFn: () => Promise.resolve(['stringCached']),
+      staleTime: Infinity,
+    })
+    const dehydratedState = dehydrate(prefetchClient)
+
+    const queryFn = vi.fn(() => Promise.resolve(['string']))
+    const suspenseQueryFn = vi.fn(() => Promise.resolve(['string']))
+    const queryClient = new QueryClient()
+
+    function Header() {
+      useQuery({
+        queryKey,
+        queryFn,
+      })
+      return null
+    }
+
+    function Page() {
+      const { data } = useSuspenseQuery({
+        queryKey,
+        queryFn: suspenseQueryFn,
+      })
+      return <div>{data}</div>
+    }
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <Header />
+        <HydrationBoundary state={dehydratedState}>
+          <React.Suspense fallback="loading">
+            <Page />
+          </React.Suspense>
+        </HydrationBoundary>
+      </QueryClientProvider>,
+    )
+
+    await Promise.resolve()
+    await Promise.resolve()
+    await Promise.resolve()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(queryClient.getQueryData(queryKey)).toEqual(['stringCached'])
+    expect(suspenseQueryFn).toHaveBeenCalledTimes(0)
+
+    queryClient.clear()
+  })
+
   test('should not refetch when query has enabled set to false', async () => {
     const queryFn = vi.fn()
     const queryClient = new QueryClient()