From f4476da118b5fe04b82da91b5efbb601d0f30335 Mon Sep 17 00:00:00 2001 From: Zelys Date: Sun, 29 Mar 2026 15:58:27 -0500 Subject: [PATCH 1/2] docs(react): clarify staleTime 'static' vs Infinity with 'always' triggers --- docs/framework/react/guides/important-defaults.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/framework/react/guides/important-defaults.md b/docs/framework/react/guides/important-defaults.md index f17e777e566..dd844ff6fb7 100644 --- a/docs/framework/react/guides/important-defaults.md +++ b/docs/framework/react/guides/important-defaults.md @@ -14,6 +14,8 @@ Out of the box, TanStack Query is configured with **aggressive but sane** defaul - set `staleTime` to `Infinity` to never trigger a refetch until the Query is [invalidated manually](./query-invalidation.md). - set `staleTime` to `'static'` to **never** trigger a refetch, even if the Query is [invalidated manually](./query-invalidation.md). +> `'static'` and `Infinity` look similar but behave differently when `refetchOnMount`, `refetchOnWindowFocus`, or `refetchOnReconnect` are set to `"always"`. With `staleTime: Infinity`, those `"always"` triggers still fire. With `staleTime: 'static'`, they don't. The query stays frozen until you explicitly call `queryClient.resetQueries()`. Use `'static'` for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use `Infinity` when you still want manual invalidation to work. + - Stale queries are refetched automatically in the background when: - New instances of the query mount - The window is refocused From b2e57fc4b18b11fddfc25ecf727de12c12fa70c3 Mon Sep 17 00:00:00 2001 From: Zelys Date: Mon, 30 Mar 2026 11:29:32 -0500 Subject: [PATCH 2/2] docs(react): lead with invalidateQueries() distinction for staleTime: 'static' vs Infinity --- docs/framework/react/guides/important-defaults.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/framework/react/guides/important-defaults.md b/docs/framework/react/guides/important-defaults.md index dd844ff6fb7..6829882a536 100644 --- a/docs/framework/react/guides/important-defaults.md +++ b/docs/framework/react/guides/important-defaults.md @@ -14,7 +14,7 @@ Out of the box, TanStack Query is configured with **aggressive but sane** defaul - set `staleTime` to `Infinity` to never trigger a refetch until the Query is [invalidated manually](./query-invalidation.md). - set `staleTime` to `'static'` to **never** trigger a refetch, even if the Query is [invalidated manually](./query-invalidation.md). -> `'static'` and `Infinity` look similar but behave differently when `refetchOnMount`, `refetchOnWindowFocus`, or `refetchOnReconnect` are set to `"always"`. With `staleTime: Infinity`, those `"always"` triggers still fire. With `staleTime: 'static'`, they don't. The query stays frozen until you explicitly call `queryClient.resetQueries()`. Use `'static'` for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use `Infinity` when you still want manual invalidation to work. +> `'static'` and `Infinity` both prevent staleness-based refetches, but `'static'` is stricter: `queryClient.invalidateQueries()` can invalidate a query with `staleTime: Infinity`, but has no effect on `staleTime: 'static'`. `refetchOnMount`, `refetchOnWindowFocus`, and `refetchOnReconnect` set to `"always"` are also blocked by `'static'`. Use `'static'` for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use `Infinity` when you still want manual invalidation to work. - Stale queries are refetched automatically in the background when: - New instances of the query mount