feat(query-core): add refetchIntervalOnServer option

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

@@ -10,6 +10,7 @@ import {
 } from 'vitest'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { QueryClient, QueryObserver, focusManager } from '..'
+import { setIsServer } from './utils'
 import type { QueryObserverResult } from '..'
 
 describe('queryObserver', () => {
@@ -867,6 +868,57 @@ describe('queryObserver', () => {
     focusManager.setFocused(true)
   })
 
+  test('should not refetch on server by default', async () => {
+    const restoreIsServer = setIsServer(true)
+
+    const key = queryKey()
+    let count = 0
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => {
+        count++
+        return Promise.resolve('data')
+      },
+      refetchInterval: 10,
+    })
+
+    const unsubscribe = observer.subscribe(() => undefined)
+    await vi.advanceTimersByTimeAsync(30)
+
+    // Should only have the initial fetch, no refetch interval
+    expect(count).toBe(1)
+
+    unsubscribe()
+    restoreIsServer()
+  })
+
+  test('should refetch on server when refetchIntervalOnServer is true', async () => {
+    const restoreIsServer = setIsServer(true)
+
+    const key = queryKey()
+    let count = 0
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: () => {
+        count++
+        return Promise.resolve('data')
+      },
+      refetchInterval: 10,
+      refetchIntervalOnServer: true,
+    })
+
+    const unsubscribe = observer.subscribe(() => undefined)
+    await vi.advanceTimersByTimeAsync(30)
+
+    // Should have the initial fetch plus refetches from the interval
+    expect(count).toBeGreaterThan(1)
+
+    unsubscribe()
+    restoreIsServer()
+  })
+
   test('should not use replaceEqualDeep for select value when structuralSharing option is true', async () => {
     const key = queryKey()
 

packages/query-core/src/queryObserver.ts

@@ -389,7 +389,7 @@ export class QueryObserver<
     this.#currentRefetchInterval = nextInterval
 
     if (
-      isServer ||
+      (isServer && !this.options.refetchIntervalOnServer) ||
       resolveEnabled(this.options.enabled, this.#currentQuery) === false ||
       !isValidTimeout(this.#currentRefetchInterval) ||
       this.#currentRefetchInterval === 0

packages/query-core/src/types.ts

@@ -350,6 +350,18 @@ export interface QueryObserverOptions<
    * Defaults to `false`.
    */
   refetchIntervalInBackground?: boolean
+  /**
+   * If set to `true`, the refetch interval will be active even in server environments
+   * (where `typeof window === 'undefined'`).
+   *
+   * By default, `refetchInterval` is paused on the server because most server-side
+   * rendering scenarios don't need polling. However, long-running server processes
+   * (like daemons or background workers) that use TanStack Query for data synchronization
+   * may need polling to function correctly.
+   *
+   * Defaults to `false`.
+   */
+  refetchIntervalOnServer?: boolean
   /**
    * If set to `true`, the query will refetch on window focus if the data is stale.
    * If set to `false`, the query will not refetch on window focus.