fix(react-query): resolve hydration mismatch in SSR with prefetched queries

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

@@ -1494,4 +1494,179 @@ describe('queryObserver', () => {
       unsubscribe2()
     })
   })
+
+  describe('SSR Hydration', () => {
+    describe('Hydration Mismatch Problem', () => {
+      test('should demonstrate hydration mismatch issue (before fix)', () => {
+        const key = queryKey()
+
+        queryClient.setQueryData(key, { amount: 10 })
+        const cache = queryClient.getQueryCache().find({ queryKey: key })
+        if (cache) {
+          cache.state.dataUpdatedAt = 0
+          cache.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueryObserver(queryClient, {
+          queryKey: key,
+          queryFn: () => ({ amount: 10 }),
+        })
+
+        const clientResult = observer.getCurrentResult()
+
+        expect(clientResult).toMatchObject({
+          status: 'success',
+          data: { amount: 10 },
+          isLoading: false,
+          isPending: false,
+        })
+      })
+    })
+
+    describe('Solution with getServerResult', () => {
+      test('getServerResult should return pending state for hydrated data', () => {
+        const key = queryKey()
+
+        queryClient.setQueryData(key, { amount: 10 })
+        const cache = queryClient.getQueryCache().find({ queryKey: key })
+        if (cache) {
+          cache.state.dataUpdatedAt = 0
+          cache.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueryObserver(queryClient, {
+          queryKey: key,
+          queryFn: () => ({ amount: 10 }),
+        })
+
+        const clientResult = observer.getCurrentResult()
+        expect(clientResult).toMatchObject({
+          status: 'success',
+          data: { amount: 10 },
+          isLoading: false,
+        })
+
+        const serverResult = observer.getServerResult()
+        expect(serverResult).toMatchObject({
+          status: 'pending',
+          data: undefined,
+          isLoading: false,
+          isPending: true,
+          isSuccess: false,
+        })
+      })
+
+      test('should handle fetching state during hydration', () => {
+        const key = queryKey()
+
+        queryClient.setQueryData(key, { amount: 10 })
+        const cache = queryClient.getQueryCache().find({ queryKey: key })
+        if (cache) {
+          cache.state.dataUpdatedAt = 0
+          cache.state.fetchStatus = 'fetching'
+        }
+
+        const observer = new QueryObserver(queryClient, {
+          queryKey: key,
+          queryFn: () => ({ amount: 10 }),
+        })
+
+        const serverResult = observer.getServerResult()
+        expect(serverResult).toMatchObject({
+          status: 'pending',
+          fetchStatus: 'fetching',
+          isLoading: true,
+          isPending: true,
+        })
+      })
+
+      test('should return normal result for non-hydrated data', () => {
+        const key = queryKey()
+
+        queryClient.setQueryData(key, { amount: 10 })
+        const cache = queryClient.getQueryCache().find({ queryKey: key })
+        if (cache) {
+          cache.state.dataUpdatedAt = Date.now()
+        }
+
+        const observer = new QueryObserver(queryClient, {
+          queryKey: key,
+          queryFn: () => ({ amount: 10 }),
+        })
+
+        const clientResult = observer.getCurrentResult()
+        const serverResult = observer.getServerResult()
+
+        expect(serverResult.status).toBe(clientResult.status)
+        expect(serverResult.data).toBe(clientResult.data)
+        expect(serverResult.isLoading).toBe(clientResult.isLoading)
+      })
+
+      test('should handle error state correctly', () => {
+        const key = queryKey()
+        const error = new Error('fetch error')
+
+        queryClient.getQueryCache().build(
+          queryClient,
+          {
+            queryKey: key,
+            queryFn: () => Promise.reject(error),
+          },
+          {
+            status: 'error',
+            error,
+            data: undefined,
+            dataUpdatedAt: 0,
+            dataUpdateCount: 0,
+            errorUpdateCount: 1,
+            errorUpdatedAt: Date.now(),
+            fetchFailureCount: 1,
+            fetchFailureReason: error,
+            fetchMeta: null,
+            fetchStatus: 'idle',
+            isInvalidated: false,
+          },
+        )
+
+        const observer = new QueryObserver(queryClient, {
+          queryKey: key,
+          queryFn: () => Promise.reject(error),
+        })
+
+        const serverResult = observer.getServerResult()
+
+        expect(serverResult).toMatchObject({
+          status: 'error',
+          error,
+          isError: true,
+        })
+      })
+    })
+
+    describe('Integration with useSyncExternalStore', () => {
+      test('should provide different snapshots for server and client', () => {
+        const key = queryKey()
+
+        queryClient.setQueryData(key, 'hydrated')
+        const cache = queryClient.getQueryCache().find({ queryKey: key })
+        if (cache) {
+          cache.state.dataUpdatedAt = 0
+        }
+
+        const observer = new QueryObserver(queryClient, {
+          queryKey: key,
+          queryFn: () => 'data',
+        })
+
+        const getSnapshot = () => observer.getCurrentResult()
+        const getServerSnapshot = () => observer.getServerResult()
+
+        const clientSnapshot = getSnapshot()
+        const serverSnapshot = getServerSnapshot()
+
+        expect(clientSnapshot.status).toBe('success')
+        expect(serverSnapshot.status).toBe('pending')
+      })
+    })
+  })
 })

packages/query-core/src/queryObserver.ts

@@ -23,6 +23,7 @@ import type {
   QueryKey,
   QueryObserverBaseResult,
   QueryObserverOptions,
+  QueryObserverPendingResult,
   QueryObserverResult,
   QueryOptions,
   RefetchOptions,
@@ -264,6 +265,31 @@ export class QueryObserver<
     return this.#currentResult
   }
 
+  getServerResult():
+    | QueryObserverPendingResult<TData, TError>
+    | QueryObserverResult<TData, TError> {
+    const currentResult = this.#currentResult
+
+    const isHydratedData =
+      currentResult.status === 'success' &&
+      this.#currentQuery.state.dataUpdatedAt === 0
+
+    if (isHydratedData) {
+      return {
+        ...currentResult,
+        status: 'pending' as const,
+        isPending: true,
+        isSuccess: false,
+        data: undefined,
+        isLoading: currentResult.fetchStatus === 'fetching',
+        isInitialLoading: currentResult.fetchStatus === 'fetching',
+        isPlaceholderData: false,
+      }
+    }
+
+    return currentResult
+  }
+
   trackResult(
     result: QueryObserverResult<TData, TError>,
     onPropTracked?: (key: keyof QueryObserverResult) => void,

packages/react-query/src/useBaseQuery.ts

@@ -109,7 +109,7 @@ export function useBaseQuery<
       [observer, shouldSubscribe],
     ),
     () => observer.getCurrentResult(),
-    () => observer.getCurrentResult(),
+    () => observer.getServerResult(),
   )
 
   React.useEffect(() => {