* docs(react): add polling guide Adds a dedicated guide for refetchInterval-based polling. The option was only mentioned in passing in important-defaults.md with no explanation of how it works, how to adapt it dynamically, or how it interacts with window focus, networkMode, and the enabled flag. Covers: - Basic setup and independence from staleTime - Dynamic intervals via function form - refetchIntervalInBackground for dashboards / always-on UIs - Disabling window-focus refetching for fullscreen game and kiosk UIs - Pausing polling with the enabled flag - networkMode: 'always' for unreliable navigator.onLine environments - Deduplication behavior across multiple observers Updates config.json to add the guide to the React sidebar between Window Focus Refetching and Disabling/Pausing Queries. Adds a cross-reference in important-defaults.md. * docs(react/polling): add example markers for framework portability * docs(react): fix deduplication note — timers are per observer, not per query * docs(react): address review feedback on polling guide - Remove staleTime enumeration; link to Important Defaults instead - Remove game/kiosk focus management examples (scope creep) - Rewrite pausing polling to use refetchInterval function instead of enabled: false - Fix offline support section: connectivity uses online/offline events, not navigator.onLine - Fix deduplication note: remove queuing implication and em dash - Add non-browser environments note pointing to React Native guide * docs(solid,vue): add polling guide framework ports * docs: wrap React Native section in markers for framework port exclusion * ci: apply automated fixes --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
4.4 KiB
| id | title |
|---|---|
| important-defaults | Important Defaults |
Out of the box, TanStack Query is configured with aggressive but sane defaults. Sometimes these defaults can catch new users off guard or make learning/debugging difficult if they are unknown by the user. Keep them in mind as you continue to learn and use TanStack Query:
- Query instances via
useQueryoruseInfiniteQueryby default consider cached data as stale.
To change this behavior, you can configure your queries both globally and per-query using the
staleTimeoption. Specifying a longerstaleTimemeans queries will not refetch their data as often
- A Query that has a
staleTimeset is considered fresh until thatstaleTimehas elapsed.- set
staleTimeto e.g.2 * 60 * 1000to make sure data is read from the cache, without triggering any kinds of refetches, for 2 minutes, or until the Query is invalidated manually. - set
staleTimetoInfinityto never trigger a refetch until the Query is invalidated manually. - set
staleTimeto'static'to never trigger a refetch, even if the Query is invalidated manually.
- set
'static'andInfinityboth prevent staleness-based refetches, but'static'is stricter:queryClient.invalidateQueries()can invalidate a query withstaleTime: Infinity, but has no effect onstaleTime: 'static'.refetchOnMount,refetchOnWindowFocus, andrefetchOnReconnectset 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. UseInfinitywhen 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
- The network is reconnected
Setting
staleTimeis the recommended way to avoid excessive refetches, but you can also customize the points in time for refetches by setting options likerefetchOnMount,refetchOnWindowFocusandrefetchOnReconnect.
-
Queries can optionally be configured with a
refetchIntervalto trigger refetches periodically, which is independent of thestaleTimesetting. See Polling for details. -
Query results that have no more active instances of
useQuery,useInfiniteQueryor query observers are labeled as "inactive" and remain in the cache in case they are used again at a later time. -
By default, "inactive" queries are garbage collected after 5 minutes.
To change this, you can alter the default
gcTimefor queries to something other than1000 * 60 * 5milliseconds. -
Queries that fail are silently retried 3 times, with exponential backoff delay before capturing and displaying an error to the UI.
To change this, you can alter the default
retryandretryDelayoptions for queries to something other than3and the default exponential backoff function.
- Query results by default are structurally shared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to useMemo and useCallback. If this concept sounds foreign, then don't worry about it! 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the
config.structuralSharingflag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can provide your own custom function asconfig.structuralSharingto compute a value from the old and new responses, retaining references as required.
Further Reading
Have a look at the following articles from our Community Resources for further explanations of the defaults: