fix: no hydration when new promise comes in

integrations/react-next-15/app/_action.ts

@@ -0,0 +1,11 @@
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { countRef } from './make-query-client'
+
+export async function queryExampleAction() {
+  await Promise.resolve()
+  countRef.current++
+  revalidatePath('/', 'page')
+  return undefined
+}

integrations/react-next-15/app/client-component.tsx

@@ -8,10 +8,14 @@ export function ClientComponent() {
   const query = useQuery({
     queryKey: ['data'],
     queryFn: async () => {
-      await new Promise((r) => setTimeout(r, 1000))
+      const { count } = await (
+        await fetch('http://localhost:3000/count')
+      ).json()
+
       return {
         text: 'data from client',
         date: Temporal.PlainDate.from('2023-01-01'),
+        count,
       }
     },
   })
@@ -26,7 +30,7 @@ export function ClientComponent() {
 
   return (
     <div>
-      {query.data.text} - {query.data.date.toJSON()}
+      {query.data.text} - {query.data.date.toJSON()} - {query.data.count}
     </div>
   )
 }

integrations/react-next-15/app/count/route.ts

@@ -0,0 +1,5 @@
+import { countRef } from '../make-query-client'
+
+export const GET = () => {
+  return Response.json({ count: countRef.current })
+}

integrations/react-next-15/app/make-query-client.ts

@@ -10,6 +10,10 @@ const plainDate = {
   test: (v) => v instanceof Temporal.PlainDate,
 } satisfies TsonType<Temporal.PlainDate, string>
 
+export const countRef = {
+  current: 0,
+}
+
 export const tson = createTson({
   types: [plainDate],
 })
@@ -22,16 +26,23 @@ export function makeQueryClient() {
          * Called when the query is rebuilt from a prefetched
          * promise, before the query data is put into the cache.
          */
-        deserializeData: tson.deserialize,
+        deserializeData: (data) => {
+          return tson.deserialize(data)
+        },
       },
       queries: {
         staleTime: 60 * 1000,
       },
       dehydrate: {
-        serializeData: tson.serialize,
-        shouldDehydrateQuery: (query) =>
-          defaultShouldDehydrateQuery(query) ||
-          query.state.status === 'pending',
+        serializeData: (data) => {
+          return tson.serialize(data)
+        },
+        shouldDehydrateQuery: (query) => {
+          return (
+            defaultShouldDehydrateQuery(query) ||
+            query.state.status === 'pending'
+          )
+        },
       },
     },
   })

integrations/react-next-15/app/page.tsx

@@ -1,30 +1,41 @@
+import { headers } from 'next/headers'
 import React from 'react'
 import { HydrationBoundary, dehydrate } from '@tanstack/react-query'
 import { Temporal } from '@js-temporal/polyfill'
 import { ClientComponent } from './client-component'
-import { makeQueryClient, tson } from './make-query-client'
+import { makeQueryClient } from './make-query-client'
+import { queryExampleAction } from './_action'
 
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
-
-export default async function Home() {
+export default function Home() {
   const queryClient = makeQueryClient()
 
-  void queryClient.prefetchQuery({
+  queryClient.prefetchQuery({
     queryKey: ['data'],
     queryFn: async () => {
-      await sleep(2000)
+      const { count } = await (
+        await fetch('http://localhost:3000/count', {
+          headers: await headers(),
+        })
+      ).json()
+
       return {
         text: 'data from server',
         date: Temporal.PlainDate.from('2024-01-01'),
+        count,
       }
     },
   })
 
+  const state = dehydrate(queryClient)
+
   return (
     <main>
-      <HydrationBoundary state={dehydrate(queryClient)}>
+      <HydrationBoundary state={state}>
         <ClientComponent />
       </HydrationBoundary>
+      <form action={queryExampleAction}>
+        <button type="submit">Increment</button>
+      </form>
     </main>
   )
 }

integrations/react-next-15/app/providers.tsx

@@ -1,16 +1,39 @@
+// In Next.js, this file would be called: app/providers.tsx
 'use client'
-import { QueryClientProvider } from '@tanstack/react-query'
+
+// Since QueryClientProvider relies on useContext under the hood, we have to put 'use client' on top
+import { QueryClientProvider, isServer } from '@tanstack/react-query'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
-import * as React from 'react'
+import type { QueryClient } from '@tanstack/react-query'
 import { makeQueryClient } from '@/app/make-query-client'
 
+let browserQueryClient: QueryClient | undefined = undefined
+
+function getQueryClient() {
+  if (isServer) {
+    // Server: always make a new query client
+    return makeQueryClient()
+  } else {
+    // Browser: make a new query client if we don't already have one
+    // This is very important, so we don't re-make a new client if React
+    // suspends during the initial render. This may not be needed if we
+    // have a suspense boundary BELOW the creation of the query client
+    if (!browserQueryClient) browserQueryClient = makeQueryClient()
+    return browserQueryClient
+  }
+}
+
 export default function Providers({ children }: { children: React.ReactNode }) {
-  const [queryClient] = React.useState(() => makeQueryClient())
+  // NOTE: Avoid useState when initializing the query client if you don't
+  //       have a suspense boundary between this and the code that may
+  //       suspend because React will throw away the client on the initial
+  //       render if it suspends and there is no boundary
+  const queryClient = getQueryClient()
 
   return (
     <QueryClientProvider client={queryClient}>
       {children}
-      <ReactQueryDevtools />
+      {<ReactQueryDevtools />}
     </QueryClientProvider>
   )
 }

packages/query-core/package.json

@@ -29,7 +29,8 @@
     "test:lib": "vitest",
     "test:lib:dev": "pnpm run test:lib --watch",
     "test:build": "publint --strict && attw --pack",
-    "build": "tsup"
+    "build": "tsup",
+    "build:dev": "tsup --watch"
   },
   "type": "module",
   "types": "build/legacy/index.d.ts",

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

@@ -1066,4 +1066,80 @@ describe('dehydration and rehydration', () => {
     clientQueryClient.clear()
     serverQueryClient.clear()
   })
+
+  test('should overwrite data when a new promise is streamed in', async () => {
+    const serializeDataMock = vi.fn((data: any) => data)
+    const deserializeDataMock = vi.fn((data: any) => data)
+
+    const countRef = { current: 0 }
+    // --- server ---
+    const serverQueryClient = createQueryClient({
+      defaultOptions: {
+        dehydrate: {
+          shouldDehydrateQuery: () => true,
+          serializeData: serializeDataMock,
+        },
+      },
+    })
+
+    const query = {
+      queryKey: ['data'],
+      queryFn: async () => {
+        await sleep(10)
+        return countRef.current
+      },
+    }
+
+    const promise = serverQueryClient.prefetchQuery(query)
+
+    let dehydrated = dehydrate(serverQueryClient)
+
+    // --- client ---
+
+    const clientQueryClient = createQueryClient({
+      defaultOptions: {
+        hydrate: {
+          deserializeData: deserializeDataMock,
+        },
+      },
+    })
+
+    hydrate(clientQueryClient, dehydrated)
+
+    await promise
+    await waitFor(() =>
+      expect(clientQueryClient.getQueryData(query.queryKey)).toBe(0),
+    )
+
+    expect(serializeDataMock).toHaveBeenCalledTimes(1)
+    expect(serializeDataMock).toHaveBeenCalledWith(0)
+
+    expect(deserializeDataMock).toHaveBeenCalledTimes(1)
+    expect(deserializeDataMock).toHaveBeenCalledWith(0)
+
+    // --- server ---
+    countRef.current++
+    serverQueryClient.clear()
+    const promise2 = serverQueryClient.prefetchQuery(query)
+
+    dehydrated = dehydrate(serverQueryClient)
+
+    // --- client ---
+
+    hydrate(clientQueryClient, dehydrated)
+
+    await promise2
+    await waitFor(() =>
+      expect(clientQueryClient.getQueryData(query.queryKey)).toBe(1),
+    )
+
+    expect(serializeDataMock).toHaveBeenCalledTimes(2)
+    expect(serializeDataMock).toHaveBeenCalledWith(1)
+
+    expect(deserializeDataMock).toHaveBeenCalledTimes(2)
+    expect(deserializeDataMock).toHaveBeenCalledWith(1)
+
+    clientQueryClient.clear()
+    serverQueryClient.clear()
+  })
 })

packages/query-core/src/hydration.ts

@@ -82,6 +82,9 @@ function dehydrateQuery(
     queryHash: query.queryHash,
     ...(query.state.status === 'pending' && {
       promise: query.promise?.then(serializeData).catch((error) => {
+        if ('digest' in error && error.digest === 'DYNAMIC_SERVER_USAGE') {
+          return Promise.reject(error)
+        }
         if (process.env.NODE_ENV !== 'production') {
           console.error(
             `A query that was dehydrated as pending ended up rejecting. [${query.queryHash}]: ${error}; The error will be redacted in production builds`,

packages/react-query/package.json

@@ -31,6 +31,7 @@
     "test:build": "publint --strict && attw --pack",
     "build": "pnpm build:tsup && pnpm build:codemods",
     "build:tsup": "tsup",
+    "build:tsup:dev": "tsup --watch",
     "build:codemods": "cpy ../query-codemods/* ./build/codemods"
   },
   "type": "module",

packages/react-query/src/HydrationBoundary.tsx

@@ -73,7 +73,10 @@ export const HydrationBoundary = ({
         } else {
           const hydrationIsNewer =
             dehydratedQuery.state.dataUpdatedAt >
-            existingQuery.state.dataUpdatedAt
+              existingQuery.state.dataUpdatedAt ||
+            // @ts-expect-error
+            dehydratedQuery.promise?.status !== existingQuery.promise?.status
+
           const queryAlreadyQueued = hydrationQueue?.find(
             (query) => query.queryHash === dehydratedQuery.queryHash,
           )