TkDodo
commented
1 month ago Ad 1: I think this is clearly stated by the fact that we say “depending on your staleTime settings). This is a general concept in React Query and applies to all forms of refetches: If data is in the cache, we return it immediately, and potentially make a background refetch. The QueryKey docs are not the right place to outline this. We have dedicated caching and important defaults sections for that.
Ad 2:
If data is available in the cache and has not been garbage collected, this may not be accurate.
Well yes, but again, this is true for every refetch in react-query. Adding placeholderData for better pagination won’t change that - it addresses the “hard loading” scenario.
Describe the bug
Improvement Proposal for Query States Documentation From my experience and testing with Tanstack Query, I have identified a few areas where the documentation could benefit from added clarity, particularly around query key changes, caching behavior, and the interaction between different states such as isPending, isFetching, and isRefetching.
"Any time a variable changes, queries will be refetched automatically (depending on your staleTime settings)."
This statement can initially lead one to believe that a query key change will immediately trigger a refetch. However, after testing, it became clear that isRefetching behaves differently depending on whether the query key is in the cache and whether the data is considered stale:
If the query key is not in the cache, the query undergoes reinitialization, resulting in isPending === true and isFetching === true, meaning isRefetching === false.
When the query key exists in the cache and hasn’t been garbage collected (i.e., within the gcTime), and the data is stale due to a prior fetch with the same query key, the stale data can be reused while the query performs a background refetch. In this case, isPending === false and isFetching === true, resulting in isRefetching === true.
It would be helpful to clearly state this behavior in the Query Keys section, as this section appears early in the documentation and shapes the understanding of how query key changes and refetching work. Clarifying these distinctions would prevent confusion about when isRefetching will be true, especially when dealing with cache and stale data.
When a query key changes (e.g., from page 1 to page 2), the new query key will only trigger a fresh fetch if the previous query key is not present in the cache. If the previous query’s data is stale but still exists in the cache (and has not been garbage collected), it can be reused while a background refetch occurs, without changing the pending state.
This raises a question regarding the statement in the Paginated Queries section, which quotes:
"The UI jumps in and out of the success and pending states because each new page is treated like a brand new query."
If data is available in the cache and has not been garbage collected, this may not be accurate. The UI should not necessarily jump between states if the previous data can be reused. This jumping behavior seems to only occur when paginating for the first time; subsequent pagination should not require such state changes if cached data is still available.
Your minimal, reproducible example
https://tanstack.com/query/latest
Steps to reproduce
Documentation
Expected behavior
To enhance clarity and reduce confusion, I propose the following updates to the Tanstack Query documentation:
Explicitly clarify how isRefetching behaves based on whether the query key is cached, whether the data is stale, and how this affects the isPending and isFetching states.
Clearly indicate that a fresh fetch occurs only when the query key is not present in the cache. If there was a prior fetch with the same query key, and the previous data has not been garbage collected (i.e., it is still within the gcTime) and is stale, that data can be reused while a background refetch occurs.
Provide additional details on how cached data is reused while refetching occurs and when a query is fully reinitialized due to an absence of cached data.
These clarifications should be included in the Query Keys section of the documentation, as it is one of the early sections and sets the foundation for understanding query state management. This would help developers better grasp the complexities of query key changes, caching, and fetching states from the outset.
This behavior aligns with caching principles but could be further clarified to help developers understand when to expect cached data and when a full reinitialization of the query occurs.
How often does this bug happen?
None
Screenshots or Videos
No response
Platform
All Browsers
Tanstack Query adapter
None
TanStack Query version
latest
TypeScript version
No response
Additional context
No response