fix(react-query/HydrationBoundary): prevent unnecessary refetch during hydration

.changeset/fix-hydration-double-fetch.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/query-core': patch
+'@tanstack/react-query': patch
+---
+
+fix(react-query/HydrationBoundary): prevent unnecessary refetch during hydration

docs/framework/react/guides/ssr.md

@@ -536,7 +536,7 @@ This is much better, but if we want to improve this further we can flatten this
 
 A query is considered stale depending on when it was `dataUpdatedAt`. A caveat here is that the server needs to have the correct time for this to work properly, but UTC time is used, so timezones do not factor into this.
 
-Because `staleTime` defaults to `0`, queries will be refetched in the background on page load by default. You might want to use a higher `staleTime` to avoid this double fetching, especially if you don't cache your markup.
+Because `staleTime` defaults to `0`, queries will be refetched in the background on page load by default. When using `HydrationBoundary`, React Query intelligently handles this: if the hydrated data is still fresh (within `staleTime`), it prevents unnecessary refetching during hydration. However, if the hydrated data is stale (e.g., from cached markup where the server fetch happened long ago), a refetch will be triggered. You can always force a refetch by setting `refetchOnMount` to `'always'`. For other approaches like `initialData`, you might want to use a higher `staleTime` to avoid double fetching.
 
 This refetching of stale queries is a perfect match when caching markup in a CDN! You can set the cache time of the page itself decently high to avoid having to re-render pages on the server, but configure the `staleTime` of the queries lower to make sure data is refetched in the background as soon as a user visits the page. Maybe you want to cache the pages for a week, but refetch the data automatically on page load if it's older than a day?
 

docs/framework/react/reference/hydration.md

@@ -114,6 +114,8 @@ function App() {
 
 > Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 
+> Note: `HydrationBoundary` intelligently prevents unnecessary refetching during hydration. Queries being hydrated will not trigger a refetch on mount if the data is still fresh (within `staleTime`). However, if the hydrated data is stale (e.g., from cached markup), a refetch will be triggered. You can always force a refetch by setting `refetchOnMount` to `'always'`.
+
 **Options**
 
 - `state: DehydratedState`

packages/query-core/src/queryObserver.ts

@@ -96,7 +96,25 @@ export class QueryObserver<
     if (this.listeners.size === 1) {
       this.#currentQuery.addObserver(this)
 
-      if (shouldFetchOnMount(this.#currentQuery, this.options)) {
+      // Check if this query is pending hydration via options._isHydrating
+      // If so, skip fetch unless:
+      // - refetchOnMount is explicitly 'always', or
+      // - the hydrated data is stale (e.g., cached markup scenario where
+      //   server fetch happened long ago)
+      const resolvedRefetchOnMount =
+        typeof this.options.refetchOnMount === 'function'
+          ? this.options.refetchOnMount(this.#currentQuery)
+          : this.options.refetchOnMount
+
+      const shouldSkipFetchForHydration =
+        this.options._isHydrating &&
+        resolvedRefetchOnMount !== 'always' &&
+        !isStale(this.#currentQuery, this.options)
+
+      if (
+        shouldFetchOnMount(this.#currentQuery, this.options) &&
+        !shouldSkipFetchForHydration
+      ) {
         this.#executeFetch()
       } else {
         this.updateResult()

packages/query-core/src/types.ts

@@ -434,6 +434,12 @@ export interface QueryObserverOptions<
 
   _optimisticResults?: 'optimistic' | 'isRestoring'
 
+  /**
+   * Internal flag to indicate this query is pending hydration.
+   * When true, the observer will skip fetching on mount unless refetchOnMount is 'always'.
+   */
+  _isHydrating?: boolean
+
   /**
    * Enable prefetching during rendering
    */

packages/react-query/src/HydrationBoundary.tsx

@@ -3,6 +3,7 @@ import * as React from 'react'
 
 import { hydrate } from '@tanstack/query-core'
 import { useQueryClient } from './QueryClientProvider'
+import { IsHydratingProvider } from './IsHydratingProvider'
 import type {
   DehydratedState,
   HydrateOptions,
@@ -50,62 +51,92 @@ export const HydrationBoundary = ({
   // If the transition is aborted, we will have hydrated any _new_ queries, but
   // we throw away the fresh data for any existing ones to avoid unexpectedly
   // updating the UI.
-  const hydrationQueue: DehydratedState['queries'] | undefined =
-    React.useMemo(() => {
-      if (state) {
-        if (typeof state !== 'object') {
-          return
-        }
+  // Create a mutable ref object to hold pending query hashes
+  // This allows us to add/remove hashes without triggering re-renders
+  const hydratingQueriesRef = React.useRef<Set<string>>(new Set())
+
+  const hydrationQueue = React.useMemo(() => {
+    if (state) {
+      if (typeof state !== 'object') {
+        return undefined
+      }
+
+      const queryCache = client.getQueryCache()
+      // State is supplied from the outside and we might as well fail
+      // gracefully if it has the wrong shape, so while we type `queries`
+      // as required, we still provide a fallback.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const queries = state.queries || []
+
+      const newQueries: DehydratedState['queries'] = []
+      const existingQueries: DehydratedState['queries'] = []
+      for (const dehydratedQuery of queries) {
+        const existingQuery = queryCache.get(dehydratedQuery.queryHash)
 
-        const queryCache = client.getQueryCache()
-        // State is supplied from the outside and we might as well fail
-        // gracefully if it has the wrong shape, so while we type `queries`
-        // as required, we still provide a fallback.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        const queries = state.queries || []
-
-        const newQueries: DehydratedState['queries'] = []
-        const existingQueries: DehydratedState['queries'] = []
-        for (const dehydratedQuery of queries) {
-          const existingQuery = queryCache.get(dehydratedQuery.queryHash)
-
-          if (!existingQuery) {
-            newQueries.push(dehydratedQuery)
-          } else {
-            const hydrationIsNewer =
-              dehydratedQuery.state.dataUpdatedAt >
-                existingQuery.state.dataUpdatedAt ||
-              (dehydratedQuery.promise &&
-                existingQuery.state.status !== 'pending' &&
-                existingQuery.state.fetchStatus !== 'fetching' &&
-                dehydratedQuery.dehydratedAt !== undefined &&
-                dehydratedQuery.dehydratedAt >
-                  existingQuery.state.dataUpdatedAt)
-
-            if (hydrationIsNewer) {
-              existingQueries.push(dehydratedQuery)
-            }
+        if (!existingQuery) {
+          newQueries.push(dehydratedQuery)
+        } else {
+          const hydrationIsNewer =
+            dehydratedQuery.state.dataUpdatedAt >
+              existingQuery.state.dataUpdatedAt ||
+            (dehydratedQuery.promise &&
+              existingQuery.state.status !== 'pending' &&
+              existingQuery.state.fetchStatus !== 'fetching' &&
+              dehydratedQuery.dehydratedAt !== undefined &&
+              dehydratedQuery.dehydratedAt > existingQuery.state.dataUpdatedAt)
+
+          if (hydrationIsNewer) {
+            existingQueries.push(dehydratedQuery)
           }
         }
+      }
 
-        if (newQueries.length > 0) {
-          // It's actually fine to call this with queries/state that already exists
-          // in the cache, or is older. hydrate() is idempotent for queries.
-          // eslint-disable-next-line react-hooks/refs
-          hydrate(client, { queries: newQueries }, optionsRef.current)
-        }
-        if (existingQueries.length > 0) {
-          return existingQueries
+      if (newQueries.length > 0) {
+        // It's actually fine to call this with queries/state that already exists
+        // in the cache, or is older. hydrate() is idempotent for queries.
+        // eslint-disable-next-line react-hooks/refs
+        hydrate(client, { queries: newQueries }, optionsRef.current)
+      }
+
+      if (existingQueries.length > 0) {
+        // Add pending hashes to the mutable ref
+        /* eslint-disable react-hooks/refs */
+        for (const dehydratedQuery of existingQueries) {
+          hydratingQueriesRef.current.add(dehydratedQuery.queryHash)
         }
+        /* eslint-enable react-hooks/refs */
+        return existingQueries
       }
-      return undefined
-    }, [client, state])
+    }
+    return undefined
+  }, [client, state])
 
   React.useEffect(() => {
     if (hydrationQueue) {
       hydrate(client, { queries: hydrationQueue }, optionsRef.current)
     }
+
+    const clearPendingQueries = () => {
+      if (hydrationQueue) {
+        for (const dehydratedQuery of hydrationQueue) {
+          hydratingQueriesRef.current.delete(dehydratedQuery.queryHash)
+        }
+      }
+    }
+
+    // Clear pending hydration flags after hydration completes
+    clearPendingQueries()
+
+    // Cleanup: also clear on unmount in case component unmounts before effect runs
+    return clearPendingQueries
   }, [client, hydrationQueue])
 
-  return children as React.ReactElement
+  // Provide the mutable Set to children
+  // Children can check set.has(hash) without needing re-renders
+  // eslint-disable-next-line react-hooks/refs
+  const contextValue = React.useMemo(() => hydratingQueriesRef.current, [])
+
+  return (
+    <IsHydratingProvider value={contextValue}>{children}</IsHydratingProvider>
+  )
 }

packages/react-query/src/IsHydratingProvider.ts

@@ -0,0 +1,7 @@
+'use client'
+import * as React from 'react'
+
+const IsHydratingContext = React.createContext<Set<string>>(new Set())
+
+export const useIsHydrating = () => React.useContext(IsHydratingContext)
+export const IsHydratingProvider = IsHydratingContext.Provider