Short answer
TanStack Query fits frontend teams that need caching, pagination and refresh behavior around request functions they control. Its README lists fetching, caching, synchronizing and updating server state, meaning data obtained from outside the application. Choose another approach if you expect the library to supply your API access. For a search-only requirement, ahooks useRequest has a documented debounce option; for a client designed around GraphQL, Apollo Client belongs in the comparison.
Our October sandbox build succeeded in 9 seconds, and tests timed out at 900 seconds. Those results belong to commit 715574d. The adoption decision developed here is about application boundaries: where the client lives, how shared hooks reach it, and which state drives a loading indicator. Historical issue discussions provide concrete examples of those decisions. TanStack Query is the software reviewed here, rather than the dictionary word or a database query engine.
What people use query for
TkDodo reported production use of infinite queries without issues, while other participants described shared hooks, generated API hooks and search components. The accounts below name the person, application pattern and reported result. A cache is a stored result that components can reuse; sharing that result also requires agreement about the client and context that hold it. The reports show both working arrangements and integration failures within that boundary.
| Person and application | What they did | Reported outcome |
|---|---|---|
| TkDodo | Used infinite queries in production | Reported no issues in #520. |
| mauris | Shared custom query hooks through three React libraries and one React app in an Nx monorepo | Reported no equivalent provider problem on react-query 3.39.0, listing Windows, macOS and Debian environments. |
| Author of #3595 | Generated typed hooks from OpenAPI with Orval and consumed them in a Next.js workspace | Encountered provider resolution trouble and subsequently an undefined React symbol. |
| basslagter | Built a search component and delayed requests by debouncing its search value | Confirmed that the input-debounce suggestion worked. |
| sec0ndhand | Progressively moved a Rails application to React | Reported a multiple-application provider problem after upgrading to v3. |
| vsaarinen and team | Ran Cypress tests against an application making approximately ten startup requests | Reported loading spinners after moving from 2.26.4 to 3.5.11 and restored their tests by reverting to v2. |
The two shared-library accounts give a useful acceptance case. Mauris described reusable hooks working in an Nx workspace; the author of #3595 described hooks failing to find the application's client despite a provider being present. For a team distributing hooks, the relevant application is the one consuming the built package. A library build answers a different question from whether its hooks and the consuming application's provider resolve the same context.
What happened when we ran it
Our October 25 install and build succeeded; tests reached the 900-second timeout. The November 22 attempt stopped at a required-Compose-file safety check. Its error named all four accepted filenames: "unsafe repo: none of compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml exists". The run summary said "deployed with its own docker compose", but the failed safety step is the recorded stopping point. The teardown result was ok.
| October sandbox step | Recorded result | What the result answers |
|---|---|---|
| pnpm install | Succeeded in 49 seconds; 2,775 dependencies recorded; 2,356 MB on disk | Contributor dependency installation completed. |
| Build | Succeeded in 9 seconds | The recorded build command finished successfully. |
| Tests | Timed out at 900 seconds | The test command ended at its time limit. |
| Checkout | 3,631 files; approximately 222,495 source lines; 32.7 MB | The workspace had this recorded size before dependencies. |
| Repository scan | Four CI workflow files; no Dockerfile; no tests directory; monorepo workspaces | The scan identified this directory layout. |
The October configuration recorded 3 CPUs, 8 GB RAM and image lab-node:22. The test command exited with code 124 after 900 seconds. Its final lines show successful Angular example type checks for query options from a service, infinite queries with max pages, optimistic updates, automatic refetching, pagination, developer tools, RxJS and the basic example. They also show the Vue basic example's lint check and the Solid offline example's build completing.
We measured a contributor workspace with 2,356 MB on disk after installation. That figure gives contributors a concrete disk requirement for this run. Installation took 49 seconds and the build took 9 seconds after dependencies were present. The scan's missing tests directory describes the repository layout; the Nx output names tasks elsewhere in the workspace. Together, the command outcomes and task names explain exactly what the run recorded without turning individual green lines into a passing-suite count.
Where people get stuck: providers, spinners and recovery
Issue #3595 describes shared hooks failing to find an application's QueryClient even after the application configured a provider. A provider makes a client available through React context to components below it. That distinction matters when a hook comes from another package: provider ancestry and package resolution both enter the investigation. The historical reports below identify symptoms and the specific responses participants discussed.
| Symptom and source | Reported behavior | Response in the discussion |
|---|---|---|
| #1936: No QueryClient set after 3.12.0 to 3.12.1 | The reporter had a provider and still saw the error. | TkDodo suspected separate copies and contexts; turning context sharing back on did not resolve the reporter's case. |
| #3595: hooks distributed through a library | Hooks could not find the application's client. | TkDodo recommended a library peer dependency and an application-owned client/provider. One v4 participant passed defaultContext explicitly; other participants reported continuing failures. |
| #1657: successful responses with persistent loading | The reporter saw isLoading true and data undefined after moving from 2.26.4 to 3.5.11. | Reverting to v2 restored their tests. Another participant reported success without staleTime; the reporter distinguished their symptom from a structuralSharing suggestion. |
| #3584: disabled-query spinner | A query with enabled: false reported isLoading true in 4.0.0-beta.7. | Participants combined query status with fetch status after removal of the v3 idle status. |
| #2712: cached error after navigation | A v3.24.4 query displayed its old error after the boundary remounted. | TkDodo described an example using FallbackComponent and resetting both error boundaries during unmount. |
A peer dependency means the consuming application supplies the dependency rather than treating the library's copy as an independent installation choice. In #3595, TkDodo connected that arrangement to sharing the application's context and client, then suggested looking for duplicate React or React Query versions. For a shared-hooks package, record the dependency declarations alongside the built application's dependency graph. The issue author's original setup already included an application provider, so merely adding that wrapper would repeat a step they had taken.
Loading state and network activity answer different questions
The React v5 guide defines isLoading as isPending && isFetching. It also says an uncached disabled query starts with status pending and fetchStatus idle. These documented states distinguish missing data from active fetching. A filter form can therefore wait for input while its query has no data, then show a loading indicator when the first request actually starts. The guide demonstrates enabling a query after the filter receives a value.
That v5 definition gives the disabled-query discussion a useful version boundary. In #3584, participants were discussing 4.0.0-beta.7 and the replacement of v3's idle state. TkDodo explained that a query previously idle could become loading in v4. Keep those names attached to their major versions when reading an old spinner example. In an application review, write down the query status and fetch status separately so a visible spinner can be traced to the condition that rendered it.
Extra renders can look like extra requests
TkDodo reported one network request per page in a reproduction discussed in #520. He explained that the log showed extra renders as loading and fetching state changed. In the same infinite-query discussion, MaximeConan reported stopping duplicate requests by disabling refetchOnWindowFocus. Those accounts describe different observations: one concerned rendered output, while the other concerned a refresh trigger.
The cursor discussion in #520 also places pagination logic at a clear boundary. TkDodo explained that getFetchMore receives the backend response and that application code returns the next parameter from it. A nextCursor field therefore comes from the response shape rather than appearing automatically. When investigating repeated pages, collect the request URL, page parameter and focus event alongside component logs. Those records separate asking for the same page again from rendering the same result again.
Shared bundles need an application-level acceptance case
Issue #1764 describes two separately bundled React v3 applications sharing one HTML page, with one failing through a QueryClientProvider error. The reporter said one application containing multiple providers worked. That difference between separate bundles and several providers inside one app is more specific than a general claim that multiple clients fail. Sec0ndhand connected the problem to a Rails application gradually moving to React.
For a shared-hooks package, make the acceptance case resemble the consumer: import the built library into the application and exercise the hooks beneath its provider. For separately mounted applications, retain that same-page arrangement. These are recommended reproductions derived from the issue descriptions. They preserve the detail that made the reports useful: which code was bundled together, which application created the client, and where the provider sat relative to the component calling a hook.
TanStack Query vs ahooks useRequest and Apollo Client
ahooks documents request debouncing through options.debounceWait, while Apollo Client identifies itself as a GraphQL client. TanStack Query's README lists REST, GraphQL and promise-based fetching. Those documented boundaries support a selection table based on the job an application needs done. A search component's debounce requirement and a GraphQL client's role are concrete reasons to compare these projects before choosing the surrounding cache design.
| Candidate | Documented boundary | Pick it for investigation when |
|---|---|---|
| TanStack Query | The README lists REST, GraphQL and promises, plus caching, refetching, pagination and infinite scroll. | You want shared cache and refresh behavior around request functions you control. |
| ahooks useRequest | The debounce documentation exposes options.debounceWait. | Request debouncing is the central requirement and you prefer that option on the request hook. |
| Apollo Client | The Apollo Client README describes a GraphQL client. | You are selecting a client specifically around GraphQL. |
The ahooks example sets debounceWait to 300 and manual to true; its documentation says frequent triggers wait until 300 ms after the last trigger. That is a documented example, distinct from our repository measurements. The Query search discussion offers another approach: debounce the input value used by the query. Choose which interface matches the component you intend to build, then retain the API's actual behavior in the comparison rather than deriving a score from a participant's preference.
FAQ
A successful response accompanied a persistent loading spinner in vsaarinen's report after moving from react-query 2.26.4 to 3.5.11. The report names isLoading true and data undefined, and reverting to v2 restored their tests. The questions below come from issue discussions and focus on interpreting those integration reports, including the difference between an application's network result, query state and rendered indicator.
Why can useQuery remain loading after a successful network response?
Issue #1657 reports that exact symptom after the 2.26.4-to-3.5.11 upgrade. The reporter restored their tests by reverting to v2. Another participant suggested structuralSharing: false for a different rendering problem, and the original reporter explicitly distinguished that symptom from theirs. Preserve the successful network response, loading flag, missing data and package version together when using this historical report to design a reproduction.
How should a shared hooks library configure React Query dependencies and its query client?
TkDodo recommended a library peer dependency and an application-owned client/provider in #3595. His response addressed a shared scope in which library hooks use the same context and client as their consuming application. He then suggested checking for duplicate React or React Query versions. The discussion also includes a working Nx arrangement on react-query 3.39.0, giving readers a concrete dependency and packaging question to investigate.
Why does a disabled query report isLoading true, and which state should control the spinner?
The v5 guide computes isLoading from isPending && isFetching, so the indicator becomes true during the first active fetch. An uncached disabled query starts pending and idle. The question itself arose in the v4 beta discussion in #3584; the v5 disabling guide provides the current documented state names and explains why pending alone does not describe an active request.
How can I debounce React Query search requests?
Basslagter confirmed that debouncing the search value worked in #293 after directly wrapping the request function with lodash.debounce produced repeated calls after the timeout. Tanner Linsley also explained that a debounced query function needs to return a promise immediately. The thread supports the input-debounce approach, which keeps the changing search value and the function's return behavior as separate concerns.
Why are failed queries not retried when an error-boundary page remounts?
The v3.24.4 reproduction in #2712 displayed the cached error immediately after the boundary returned. TkDodo described an example using FallbackComponent and resetting both the React error boundary and Query's reset boundary during unmount. The discussion connects recovery to boundary reset behavior. Keep the navigation sequence and component identity in the reproduction, since the original symptom involved leaving and returning to a page.
Must cleanup run inside every act call when testing React Query?
Issue #432 records a reporter reducing an act warning by adding manual cleanup at the end of the test's act call. The warning concerned an update after the test's assertions, and participants discussed query timers and cleanup order. Kent C. Dodds endorsed manual cleanup as a workaround. The historical testing discussion therefore gives a specific harness behavior to reproduce when investigating that warning.
What should replace usePaginatedQuery during the v3 migration?
The v3 umbrella discussion lists removal of usePaginatedQuery, and razh described useQuery with keepPreviousData as the replacement in that migration. Keep the v3 label on this answer when interpreting older code. The migration discussion in #772 groups that change with other query and cache API changes, so the surrounding version context belongs beside any pagination example copied from that period.
What we have not tested yet
The October run ended without a completed overall test verdict, and the November safety failure prevented an application workload. commit 715574d is the measured checkout; the November 20 release lists @tanstack/react-query@5.108.2. We have not reproduced the historical provider, spinner, cached-error, timer or pagination reports on that release. Their discussion outcomes support attributed workarounds and investigation steps, rather than a current-version reliability judgment or a universal repair.
The 2,356 MB measurement is the installed contributor workspace, not a browser bundle or one adapter's installation footprint. The lab-node:22 label records configuration; actual runtime and operating-system versions require raw toolchain logs. Application latency, memory under load, adapter compatibility, server rendering, offline recovery, authentication, authorization and account-transition cache behavior remain outside this run. Query, ahooks and Apollo also have no common-workload comparison here. Those gaps are why the four editorial score dimensions remain unassessed.
The mutation-serialization question in #293 and the class-component question in #772 have no implementation answer in their readable discussions here. The next useful application run should consume the actual shared-hooks package, record exact dependency versions and provider ownership, load data, navigate away and back after an error, and inspect pagination requests. That sequence is a proposed acceptance case, not a completed test or a claim that the historical symptoms persist.


