add ability to warn when suspense queries aren't prefetched

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

@@ -1,11 +1,11 @@
 'use client'
 
 import React from 'react'
-import { useQuery } from '@tanstack/react-query'
+import { useQuery, useSuspenseQuery } from '@tanstack/react-query'
 import { Temporal } from '@js-temporal/polyfill'
 
 export function ClientComponent() {
-  const query = useQuery({
+  const query = useSuspenseQuery({
     queryKey: ['data'],
     queryFn: async () => {
       await new Promise((r) => setTimeout(r, 1000))
@@ -16,13 +16,13 @@ export function ClientComponent() {
     },
   })
 
-  if (query.isPending) {
-    return <div>Loading...</div>
-  }
+  // if (query.isPending) {
+  //   return <div>Loading...</div>
+  // }
 
-  if (query.isError) {
-    return <div>An error has occurred!</div>
-  }
+  // if (query.isError) {
+  //   return <div>An error has occurred!</div>
+  // }
 
   return (
     <div>

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

@@ -26,6 +26,7 @@ export function makeQueryClient() {
       },
       queries: {
         staleTime: 60 * 1000,
+        warnOnServerFetches: true,
       },
       dehydrate: {
         serializeData: tson.serialize,

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

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { Suspense } from 'react'
 import { HydrationBoundary, dehydrate } from '@tanstack/react-query'
 import { Temporal } from '@js-temporal/polyfill'
 import { ClientComponent } from './client-component'
@@ -9,21 +9,23 @@ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
 export default async function Home() {
   const queryClient = makeQueryClient()
 
-  void queryClient.prefetchQuery({
-    queryKey: ['data'],
-    queryFn: async () => {
-      await sleep(2000)
-      return {
-        text: 'data from server',
-        date: Temporal.PlainDate.from('2024-01-01'),
-      }
-    },
-  })
+  // void queryClient.prefetchQuery({
+  //   queryKey: ['data'],
+  //   queryFn: async () => {
+  //     await sleep(2000)
+  //     return {
+  //       text: 'data from server',
+  //       date: Temporal.PlainDate.from('2024-01-01'),
+  //     }
+  //   },
+  // })
 
   return (
     <main>
       <HydrationBoundary state={dehydrate(queryClient)}>
-        <ClientComponent />
+        <Suspense fallback={<div>Loading...</div>}>
+          <ClientComponent />
+        </Suspense>
       </HydrationBoundary>
     </main>
   )

packages/query-core/src/types.ts

@@ -223,6 +223,12 @@ export interface QueryOptions<
    * Maximum number of pages to store in the data of an infinite query.
    */
   maxPages?: number
+  /**
+   * If set to `true`, the query will warn if it is fetched on the server.
+   * Use this if you intend to only consume prefetched queries.
+   * Defaults to `false`.
+   */
+  warnOnServerFetches?: boolean
 }
 
 export interface InitialPageParam<TPageParam = unknown> {

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

@@ -903,4 +903,100 @@ describe('useSuspenseQuery', () => {
     )
     consoleErrorSpy.mockRestore()
   })
+
+  describe.only("warnOnServerFetches should warn when query isn't prefetched", () => {
+    it('global default', async () => {
+      const queryClient = createQueryClient({
+        defaultOptions: {
+          queries: {
+            warnOnServerFetches: true,
+          },
+        },
+      })
+
+      const consoleWarnSpy = vi
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {})
+
+      function App() {
+        useSuspenseQuery({
+          queryKey: queryKey(),
+          queryFn: () => Promise.resolve('data1'),
+        })
+
+        return null
+      }
+
+      renderWithClient(queryClient, <App />)
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        'A new query suspended on the server without any cache entry.',
+      )
+    })
+
+    it('local override', async () => {
+      const queryClient = createQueryClient({
+        defaultOptions: {
+          queries: {
+            warnOnServerFetches: true,
+          },
+        },
+      })
+
+      const consoleWarnSpy = vi
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {})
+
+      function App() {
+        useSuspenseQuery({
+          queryKey: queryKey(),
+          queryFn: () => Promise.resolve('data1'),
+          warnOnServerFetches: false,
+        })
+
+        return null
+      }
+
+      renderWithClient(queryClient, <App />)
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled()
+    })
+
+    it('mix of both', async () => {
+      const queryClient = createQueryClient({
+        defaultOptions: {
+          queries: {
+            warnOnServerFetches: true,
+          },
+        },
+      })
+
+      const consoleWarnSpy = vi
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {})
+
+      function Component(props: { warnOnServerFetches?: boolean }) {
+        useSuspenseQuery({
+          queryKey: queryKey(),
+          queryFn: () => Promise.resolve('data'),
+          warnOnServerFetches: props.warnOnServerFetches,
+        })
+
+        return null
+      }
+
+      function App() {
+        return (
+          <>
+            <Component />
+            <Component warnOnServerFetches={false} />
+          </>
+        )
+      }
+
+      renderWithClient(queryClient, <App />)
+
+      expect(consoleWarnSpy).not.toHaveBeenCalledTimes(1)
+    })
+  })
 })

packages/react-query/src/useBaseQuery.ts

@@ -111,6 +111,11 @@ export function useBaseQuery<
 
   // Handle suspense
   if (shouldSuspend(defaultedOptions, result)) {
+    if (defaultedOptions.warnOnServerFetches && isNewCacheEntry) {
+      console.warn(
+        'A new query suspended on the server without any cache entry.',
+      )
+    }
     throw fetchOptimistic(defaultedOptions, observer, errorResetBoundary)
   }