Merge remote-tracking branch 'upstream/main' into refactor/resolveValueOrFunction

Author: braden-w

.github/workflows/pr.yml

@@ -65,12 +65,12 @@ jobs:
         run: |
           echo "COMMIT_SHA=${{ github.event.pull_request.head.sha || github.sha }}" >> $GITHUB_ENV
       - name: Preview Bundle Size
-        uses: marocchino/sticky-pull-request-comment@28d58c4b5a5eae3bbe45348c3990dcbc2ffcdc69
+        uses: marocchino/sticky-pull-request-comment@9c40848920de7cd32a71773ba792d8b04f03bf7a
         with:
           message: |
             Sizes for commit ${{ env.COMMIT_SHA }}:
             | Branch | Bundle Size |
             |--------|--------|
-            | Main | [![](https://deno.bundlejs.com/badge?q=https://esm.sh/@tanstack/react-query/es2022/react-query.mjs&config={%22esbuild%22:{%22external%22:[%22react@^19.1.0/jsx-runtime?target=es2022%22,%22react@^19.1.0?target=es2022%22]}}&badge=detailed)](https://bundlejs.com/?q=https://esm.sh/@tanstack/react-query/es2022/react-query.mjs&config=%7B%22esbuild%22:%7B%22external%22:%5B%22react@%5E19.1.0/jsx-runtime?target=es2022%22,%22react@%5E19.1.0?target=es2022%22%5D%7D%7D) |
-            | This PR | [![](https://deno.bundlejs.com/badge?q=https://esm.sh/pr/@tanstack/react-query@${{ env.COMMIT_SHA }}/es2022/react-query.mjs&config={%22esbuild%22:{%22external%22:[%22react@^19.1.0/jsx-runtime?target=es2022%22,%22react@^19.1.0?target=es2022%22]}}&badge=detailed)](https://bundlejs.com/?q=https://esm.sh/pr/@tanstack/react-query@${{ env.COMMIT_SHA }}/es2022/react-query.mjs&config=%7B%22esbuild%22:%7B%22external%22:%5B%22react@%5E19.1.0/jsx-runtime?target=es2022%22,%22react@%5E19.1.0?target=es2022%22%5D%7D%7D) |
+            | Main | [![](https://deno.bundlejs.com/badge?q=https://esm.sh/@tanstack/react-query/es2022/react-query.mjs&config={%22esbuild%22:{%22external%22:[%22react@^19.1.1/jsx-runtime?target=es2022%22,%22react@^19.1.1?target=es2022%22]}}&badge=detailed)](https://bundlejs.com/?q=https://esm.sh/@tanstack/react-query/es2022/react-query.mjs&config=%7B%22esbuild%22:%7B%22external%22:%5B%22react@%5E19.1.1/jsx-runtime?target=es2022%22,%22react@%5E19.1.1?target=es2022%22%5D%7D%7D) |
+            | This PR | [![](https://deno.bundlejs.com/badge?q=https://esm.sh/pr/@tanstack/react-query@${{ env.COMMIT_SHA }}/es2022/react-query.mjs&config={%22esbuild%22:{%22external%22:[%22react@^19.1.1/jsx-runtime?target=es2022%22,%22react@^19.1.1?target=es2022%22]}}&badge=detailed)](https://bundlejs.com/?q=https://esm.sh/pr/@tanstack/react-query@${{ env.COMMIT_SHA }}/es2022/react-query.mjs&config=%7B%22esbuild%22:%7B%22external%22:%5B%22react@%5E19.1.1/jsx-runtime?target=es2022%22,%22react@%5E19.1.1?target=es2022%22%5D%7D%7D) |
         continue-on-error: true

docs/framework/angular/devtools.md

@@ -3,7 +3,11 @@ id: devtools
 title: Devtools
 ---
 
-> For Google Chrome users: A third-party Chrome extension is available for debugging TanStack Query directly in Chrome DevTools. This provides the same functionality as the framework-specific devtools packages. Check it out here: [TanStack Query DevTools](https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai)
+> For Chrome, Firefox, and Edge users: Third-party browser extensions are available for debugging TanStack Query directly in browser DevTools. These provide the same functionality as the framework-specific devtools packages:
+>
+> - <img alt="Chrome logo" src="https://www.google.com/chrome/static/images/chrome-logo.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Chrome](https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai)
+> - <img alt="Firefox logo" src="https://upload.wikimedia.org/wikipedia/commons/a/a0/Firefox_logo%2C_2019.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Firefox](https://addons.mozilla.org/en-US/firefox/addon/tanstack-query-devtools/)
+> - <img alt="Edge logo" src="https://upload.wikimedia.org/wikipedia/commons/9/98/Microsoft_Edge_logo_%282019%29.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Edge](https://microsoftedge.microsoft.com/addons/detail/tanstack-query-devtools/edmdpkgkacmjopodhfolmphdenmddobj)
 
 ## Enable devtools
 

docs/framework/angular/typescript.md

@@ -153,7 +153,8 @@ import '@tanstack/angular-query-experimental'
 
 declare module '@tanstack/angular-query-experimental' {
   interface Register {
-    defaultError: AxiosError
+    // Use unknown so call sites must narrow explicitly.
+    defaultError: unknown
   }
 }
 
@@ -164,7 +165,7 @@ const query = injectQuery(() => ({
 
 computed(() => {
   const error = query.error()
-  //      ^? error: AxiosError | null
+  //      ^? error: unknown | null
 })
 ```
 

docs/framework/react/community/community-projects.md

@@ -31,18 +31,28 @@ A family of libraries for building building browser and gRPC-compatible HTTP API
 
 Link: https://connectrpc.com/docs
 
-## DevTools Chrome Extension
+## DevTools Browser Extensions
 
-A Chrome browser extension that provides devtools for TanStack Query, allowing you to inspect and debug queries, mutations, and cache state directly in Chrome DevTools.
+Browser extensions for Chrome, Firefox, and Edge that provide devtools for TanStack Query, allowing you to inspect and debug queries, mutations, and cache state directly in browser DevTools.
 
-Link: https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai
+Links:
+
+- <img alt="Chrome logo" src="https://www.google.com/chrome/static/images/chrome-logo.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Chrome](https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai)
+- <img alt="Firefox logo" src="https://upload.wikimedia.org/wikipedia/commons/a/a0/Firefox_logo%2C_2019.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Firefox](https://addons.mozilla.org/en-US/firefox/addon/tanstack-query-devtools/)
+- <img alt="Edge logo" src="https://upload.wikimedia.org/wikipedia/commons/9/98/Microsoft_Edge_logo_%282019%29.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Edge](https://microsoftedge.microsoft.com/addons/detail/tanstack-query-devtools/edmdpkgkacmjopodhfolmphdenmddobj)
 
 ## GraphQL Code Generator
 
 Generate React Query hooks from your GraphQL schema
 
 Link: https://the-guild.dev/graphql/codegen
 
+## Hey API
+
+The OpenAPI to TypeScript codegen. Generate clients, SDKs, validators, and more.
+
+Link: https://heyapi.dev/openapi-ts/plugins/tanstack-query
+
 ## Http-wizard
 
 End-to-end type-safe Fastify API with typeScript magic ✨
@@ -98,6 +108,12 @@ A 2KB min, typesafe fetch wrapper that uses static TypeScript type inference and
 
 Link: https://openapi-ts.dev/openapi-react-query/
 
+## oRPC
+
+Easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards.
+
+Link: https://orpc.unnoq.com/docs/integrations/tanstack-query
+
 ## Orval
 
 Generate TypeScript client from OpenAPI specifications

docs/framework/react/community/tkdodos-blog.md

@@ -84,3 +84,47 @@ TanStack Query maintainer [TkDodo](https://bsky.app/profile/tkdodo.eu) has a ser
 ## [#19: Type-safe React Query](https://tkdodo.eu/blog/type-safe-react-query)
 
 > There's a big difference between "having types" and "being type-safe". This article tries to outline those differences and shows how you can get the best possible type-safety when using React Query together with TypeScript [Read more...](https://tkdodo.eu/blog/type-safe-react-query)
+
+## [#20: You Might Not Need React Query](https://tkdodo.eu/blog/you-might-not-need-react-query)
+
+> If your application doesn’t rely on client-side data fetching, especially when using frameworks like Next.js or Remix with built-in server components, React Query may be unnecessary. That said, it still shines in hybrid use cases (like infinite scrolling or offline support) where its smart caching and revalidation can be invaluable. [Read more...](https://tkdodo.eu/blog/you-might-not-need-react-query)
+
+## [#21: Thinking in React Query](https://tkdodo.eu/blog/thinking-in-react-query)
+
+> React Query isn’t a data-fetching library - it's an async state manager designed to treat parameters as dependencies, optimize refetch behavior via `staleTime`, and encourage declarative patterns where `queryKey` drives cache and updates. A small shift in mindset can dramatically streamline how you use React Query. [Read more...](https://tkdodo.eu/blog/thinking-in-react-query)
+
+## [#22: React Query and React Context](https://tkdodo.eu/blog/react-query-and-react-context)
+
+> React Query lets components independently manage their own data, making them self-sufficient and resilient, but when shared data (like user info fetched higher up) is needed deeper in the tree, React Context can make that implicit dependency explicit and safer. [Read more...](https://tkdodo.eu/blog/react-query-and-react-context)
+
+## [#23: Why You Want React Query](https://tkdodo.eu/blog/why-you-want-react-query)
+
+> While fetching data with `fetch` inside `useEffect` may seem simple, it quickly gets tangled with bugs like race conditions, missing loading states, stale data, and Strict Mode quirks—making async state management far more complex than it appears. [Read more...](https://tkdodo.eu/blog/why-you-want-react-query)
+
+## [#24: The Query Options API](https://tkdodo.eu/blog/the-query-options-api)
+
+> React Query v5 introduces a unified "Query Options" API - where all functions like `useQuery`, `invalidateQueries`, and imperative calls accept a single object - simplifying the interface and making reuse across different query contexts much easier while at the same time improving type-safety. [Read more...](https://tkdodo.eu/blog/the-query-options-api)
+
+## [#25: Automatic Query Invalidation after Mutations](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations)
+
+> React Query doesn’t automatically tie mutations to queries - but you can leverage "global cache callbacks" in a central `MutationCache` to define shared behaviors like invalidating queries on every mutation. [Read more...](https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations)
+
+## [#26: How Infinite Queries work](https://tkdodo.eu/blog/how-infinite-queries-work)
+
+> This blog post is a deep dive into how Infinite Queries are designed and work under the hood. Interestingly, there is no distinct InfiniteQuery representation - just a different "behaviour" attached to regular Queries. [Read more...](https://tkdodo.eu/blog/how-infinite-queries-work)
+
+## [#27: React Query API Design - Lessons Learned](https://tkdodo.eu/blog/react-query-api-design-lessons-learned)
+
+> In this talk, Dominik walks us through some of the API design choices that were made in React Query to get to its arguably good developer experience. You'll hear stories about things that went well, but also about tradeoffs and mistakes that were made, and what lessons we can all learn from those. [Read more...](https://tkdodo.eu/blog/react-query-api-design-lessons-learned)
+
+## [#28: React Query - The Bad Parts](https://tkdodo.eu/blog/react-query-the-bad-parts)
+
+> In this talk, Dominik explores the less favorable aspects of React Query and situations where it may not be the best fit. No library is perfect; every choice involves trade-offs. By the end of this talk, you'll have a better understanding of React Query's limitations and why it remains a compelling choice despite them. [Read more...](https://tkdodo.eu/blog/react-query-the-bad-parts)
+
+## [#29: Concurrent Optimistic Updates in React Query](https://tkdodo.eu/blog/concurrent-optimistic-updates-in-react-query)
+
+> Optimistic updates in React Query can cause race conditions when multiple mutations run at once, leading to inconsistent UI states. Cancelling in-flight queries helps, but overlapping invalidations may still overwrite newer updates. [Read more...](https://tkdodo.eu/blog/concurrent-optimistic-updates-in-react-query)
+
+## [#30: React Query Selectors, Supercharged](https://tkdodo.eu/blog/react-query-selectors-supercharged)
+
+> React Query’s `select` option enables components to subscribe only to the specific part of a query’s data they care about - so updating one field won’t cause unrelated UI to re-render unnecessarily. This fine-grained approach keeps full responses in the cache while optimizing component updates for performance. [Read more...](https://tkdodo.eu/blog/react-query-selectors-supercharged)

docs/framework/react/devtools.md

@@ -7,7 +7,11 @@ Wave your hands in the air and shout hooray because React Query comes with dedic
 
 When you begin your React Query journey, you'll want these devtools by your side. They help visualize all the inner workings of React Query and will likely save you hours of debugging if you find yourself in a pinch!
 
-> For Google Chrome users: A third-party Chrome extension is available for debugging TanStack Query directly in Chrome DevTools. This provides the same functionality as the framework-specific devtools packages. Check it out here: [TanStack Query DevTools](https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai)
+> For Chrome, Firefox, and Edge users: Third-party browser extensions are available for debugging TanStack Query directly in browser DevTools. These provide the same functionality as the framework-specific devtools packages:
+>
+> - <img alt="Chrome logo" src="https://www.google.com/chrome/static/images/chrome-logo.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Chrome](https://chromewebstore.google.com/detail/tanstack-query-devtools/annajfchloimdhceglpgglpeepfghfai)
+> - <img alt="Firefox logo" src="https://upload.wikimedia.org/wikipedia/commons/a/a0/Firefox_logo%2C_2019.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Firefox](https://addons.mozilla.org/en-US/firefox/addon/tanstack-query-devtools/)
+> - <img alt="Edge logo" src="https://upload.wikimedia.org/wikipedia/commons/9/98/Microsoft_Edge_logo_%282019%29.svg" width="16" height="16" class="inline mr-1 not-prose" /> [Devtools for Edge](https://microsoftedge.microsoft.com/addons/detail/tanstack-query-devtools/edmdpkgkacmjopodhfolmphdenmddobj)
 
 > For React Native users: A third-party native macOS app is available for debugging React Query in ANY js-based application. Monitor queries across devices in real-time. Check it out here: [rn-better-dev-tools](https://github.com/LovesWorking/rn-better-dev-tools)
 

docs/framework/react/guides/advanced-ssr.md

@@ -621,3 +621,11 @@ If you value DX/iteration/shipping speed with low code complexity over performan
 Server Components and streaming are still fairly new concepts and we are still figuring out how React Query fits in and what improvements we can make to the API. We welcome suggestions, feedback and bug reports!
 
 Similarly, it would be impossible to teach all the intricacies of this new paradigm all in one guide, on the first try. If you are missing some piece of information here or have suggestions on how to improve this content, also get in touch, or even better, click the "Edit on GitHub" button below and help us out.
+
+[//]: # 'Materials'
+
+## Further reading
+
+To understand if your application can benefit from React Query when also using Server Components, have a look at [You Might Not Need React Query](../../community/tkdodos-blog.md#20-you-might-not-need-react-query) from the Community Resources.
+
+[//]: # 'Materials'

docs/framework/react/guides/important-defaults.md

@@ -44,5 +44,6 @@ Have a look at the following articles from our Community Resources for further e
 
 - [Practical React Query](../../community/tkdodos-blog.md#1-practical-react-query)
 - [React Query as a State Manager](../../community/tkdodos-blog.md#10-react-query-as-a-state-manager)
+- [Thinking in React Query](../../community/tkdodos-blog.md#21-thinking-in-react-query)
 
 [//]: # 'Materials'

docs/framework/react/guides/infinite-queries.md

@@ -257,3 +257,11 @@ return useInfiniteQuery({
 ```
 
 [//]: # 'Example9'
+[//]: # 'Materials'
+
+## Further reading
+
+To get a better understanding of how Infinite Queries work under the hood, read [How Infinite Queries work](../../community/tkdodos-blog.md#26-how-infinite-queries-work) from
+the Community Resources.
+
+[//]: # 'Materials'

docs/framework/react/guides/invalidations-from-mutations.md

@@ -27,13 +27,32 @@ const queryClient = useQueryClient()
 // When this mutation succeeds, invalidate any queries with the `todos` or `reminders` query key
 const mutation = useMutation({
   mutationFn: addTodo,
-  onSuccess: () => {
-    queryClient.invalidateQueries({ queryKey: ['todos'] })
-    queryClient.invalidateQueries({ queryKey: ['reminders'] })
+  onSuccess: async () => {
+    // If you're invalidating a single query
+    await queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+    // If you're invalidating multiple queries
+    await Promise.all([
+      queryClient.invalidateQueries({ queryKey: ['todos'] }),
+      queryClient.invalidateQueries({ queryKey: ['reminders'] }),
+    ])
   },
 })
 ```
 
 [//]: # 'Example2'
 
+Returning a Promise on `onSuccess` makes sure the data is updated before the mutation is entirely complete (i.e., isPending is true until onSuccess is fulfilled)
+
+[//]: # 'Example2'
+
 You can wire up your invalidations to happen using any of the callbacks available in the [`useMutation` hook](../mutations.md)
+
+[//]: # 'Materials'
+
+## Further reading
+
+For a technique to automatically invalidate Queries after Mutations, have a look at [Automatic Query Invalidation after Mutations](../../community/tkdodos-blog.md#25-automatic-query-invalidation-after-mutations) from
+the Community Resources.
+
+[//]: # 'Materials'