Capítulo 43 de 80

Chapter 43: Migrating to React Query 3

Core Idea

v3 split the single monolithic QueryCache into a QueryClient (configuration + interaction surface) plus separate lower-level QueryCache/MutationCache instances, and replaced the old provider/hook names with QueryClientProvider/useQueryClient — the API shape that every later version builds on.

Key Concepts

  • QueryClient split: new QueryClient() auto-creates a QueryCache and MutationCache if you don't supply your own — enabling multiple clients to share one cache, and easier testing of each piece in isolation.
  • Provider consolidation: ReactQueryConfigProvider/ReactQueryCacheProviderQueryClientProvider; default query/mutation options move into new QueryClient({ defaultOptions: { queries, mutations } }) (renamed from defaultConfig).
  • No more default cache: a QueryCache/QueryClient must always be explicitly constructed — there's no implicit global one.
  • Renames: QueryCache.prefetchQuery()QueryClient.prefetchQuery() (still returns no data — use the new QueryClient.fetchQuery() if you need the resolved value); QueryCache.getQuery()/getQueries()QueryCache.find()/findAll(); QueryCache.isFetching (property) → QueryClient.isFetching() (function); useQueryCacheuseQueryClient; ReactQueryErrorResetBoundaryQueryErrorResetBoundary/useQueryErrorResetBoundary.
  • New in v3: bi-directional infinite queries, query data select, per-query/mutation default configuration, the variable-length useQueries hook, mutation retry/offline/replay support, and bundled devtools.

Key Takeaways

  1. This is the version that established the QueryClient/QueryClientProvider shape still used today — later migrations (v4, v5) build on this structure rather than replacing it.
  2. fetchQuery (returns data) vs. prefetchQuery (doesn't) was introduced here as a distinction that persisted, in spirit, through v5's queryClient.query() unification.

Connects To

  • Migrating to React Query 4: the next major version's changes.
  • QueryClient / QueryCache / MutationCache: the split introduced in this version.