Merge branch 'main' into fix_observer_result_mismatch

Author: TkDodo

.github/workflows/pr.yml

@@ -60,16 +60,12 @@ jobs:
         id: determine-sha
         run: |
           echo "COMMIT_SHA=${{ github.event.pull_request.head.sha || github.sha }}" >> $GITHUB_ENV
-      - name: Preview Bundle Size
-        uses: marocchino/sticky-pull-request-comment@fd19551a2a7c0d29677c63257f86d8ef8bb24b48
+      - name: Size Limit
+        uses: andresz1/size-limit-action@94bc357df29c36c8f8d50ea497c3e225c3c95d1d
         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.2.1/jsx-runtime?target=es2022%22,%22react@^19.2.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.2.0/jsx-runtime?target=es2022%22,%22react@%5E19.2.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.2.1/jsx-runtime?target=es2022%22,%22react@^19.2.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.2.0/jsx-runtime?target=es2022%22,%22react@%5E19.2.0?target=es2022%22%5D%7D%7D) |
-        continue-on-error: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          skip_step: install
+          build_script: build:all
   provenance:
     name: Provenance
     runs-on: ubuntu-latest

.size-limit.json

@@ -0,0 +1,15 @@
+[
+  {
+    "name": "react full",
+    "path": "packages/react-query/build/modern/index.js",
+    "limit": "12.10 kB",
+    "ignore": ["react", "react-dom"]
+  },
+  {
+    "name": "react minimal",
+    "path": "packages/react-query/build/modern/index.js",
+    "limit": "9.12 kB",
+    "import": "{ useQuery, QueryClient, QueryClientProvider }",
+    "ignore": ["react", "react-dom"]
+  }
+]

docs/framework/react/comparison.md

@@ -79,8 +79,8 @@ Feature/Capability Key:
 
 > **<sup>8</sup> React Router cache persistence** - React Router does not cache data beyond the currently matched routes. If a route is left, its data is lost.
 
-[bpl-react-query]: https://bundlephobia.com/result?p=react-query
-[bp-react-query]: https://badgen.net/bundlephobia/minzip/react-query?label=💾
+[bpl-react-query]: https://bundlephobia.com/result?p=@tanstack/react-query
+[bp-react-query]: https://badgen.net/bundlephobia/minzip/@tanstack/react-query?label=💾
 [gh-react-query]: https://github.com/tannerlinsley/react-query
 [stars-react-query]: https://img.shields.io/github/stars/tannerlinsley/react-query?label=%F0%9F%8C%9F
 [swr]: https://github.com/vercel/swr

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

@@ -532,6 +532,25 @@ Now, your `getPosts` function can return e.g. `Temporal` datetime objects and th
 
 For more information, check out the [Next.js App with Prefetching Example](../examples/nextjs-app-prefetching).
 
+### Using the Persist Adapter with Streaming
+
+If you're using the persist adapter with the [Streaming with Server Components](#streaming-with-server-components) feature, you need to be careful not to save promises to storage. Since pending queries can be dehydrated and streamed to the client, you should configure the persister to only persist successful queries:
+
+```tsx
+<PersistQueryClientProvider
+  client={queryClient}
+  persistOptions={{
+    persister,
+    // We don't want to save promises into the storage, so we only persist successful queries
+    dehydrateOptions: { shouldDehydrateQuery: defaultShouldDehydrateQuery },
+  }}
+>
+  {children}
+</PersistQueryClientProvider>
+```
+
+This ensures that only successfully resolved queries are persisted to storage, preventing serialization issues with pending promises.
+
 ## Experimental streaming without prefetching in Next.js
 
 While we recommend the prefetching solution detailed above because it flattens request waterfalls both on the initial page load **and** any subsequent page navigation, there is an experimental way to skip prefetching altogether and still have streaming SSR work: `@tanstack/react-query-next-experimental`

docs/framework/react/guides/caching.md

@@ -27,7 +27,7 @@ Let's assume we are using the default `gcTime` of **5 minutes** and the default
   - When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data.
 - Both instances of the `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` query are unmounted and no longer in use.
   - Since there are no more active instances of this query, a garbage collection timeout is set using `gcTime` to delete and garbage collect the query (defaults to **5 minutes**).
-- Before the cache timeout has completed, another instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts. The query immediately returns the available cached data while the `fetchTodos` function is being run in the background. When it completes successfully, it will populate the cache with fresh data.
+- Before the cache timeout (gcTime) has completed, another instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts. The query immediately returns the available cached data while the `fetchTodos` function is being run in the background. When it completes successfully, it will populate the cache with fresh data.
 - The final instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` unmounts.
 - No more instances of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` appear within **5 minutes**.
   - The cached data under the `['todos']` key is deleted and garbage collected.

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

@@ -95,7 +95,7 @@ so it will only be true if the query is currently fetching for the first time.
 
 ## Typesafe disabling of queries using `skipToken`
 
-If you are using TypeScript, you can use the `skipToken` to disable a query. This is useful when you want to disable a query based on a condition, but you still want to keep the query to be type safe.
+If you are using TypeScript, you can use the `skipToken` to disable a query. This is useful when you want to disable a query based on a condition, but you still want the query to be type safe.
 
 > **IMPORTANT**: `refetch` from `useQuery` will not work with `skipToken`. Calling `refetch()` on a query that uses `skipToken` will result in a `Missing queryFn` error because there is no valid query function to execute. If you need to manually trigger queries, consider using `enabled: false` instead, which allows `refetch()` to work properly. Other than this limitation, `skipToken` works the same as `enabled: false`.
 

docs/framework/react/guides/prefetching.md

@@ -26,8 +26,8 @@ Before jumping into the different specific prefetch patterns, let's look at the
   - If you want to ignore `staleTime` and instead always return data if it's available in the cache, you can use the `ensureQueryData` function.
   - Tip: If you are prefetching on the server, set a default `staleTime` higher than `0` for that `queryClient` to avoid having to pass in a specific `staleTime` to each prefetch call
 - If no instances of `useQuery` appear for a prefetched query, it will be deleted and garbage collected after the time specified in `gcTime`
-- These functions returns `Promise<void>` and thus never return query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.
-- The prefetch functions never throws errors because they usually try to fetch again in a `useQuery` which is a nice graceful fallback. If you need to catch errors, use `fetchQuery`/`fetchInfiniteQuery` instead.
+- These functions return `Promise<void>` and thus never return query data. If that's something you need, use `fetchQuery`/`fetchInfiniteQuery` instead.
+- The prefetch functions never throw errors because they usually try to fetch again in a `useQuery` which is a nice graceful fallback. If you need to catch errors, use `fetchQuery`/`fetchInfiniteQuery` instead.
 
 This is how you use `prefetchQuery`:
 
@@ -433,6 +433,6 @@ queryClient.setQueryData(['todos'], todos)
 
 For a deep-dive on how to get data into your Query Cache before you fetch, see the [article Seeding the Query Cache by TkDodo](https://tkdodo.eu/blog/seeding-the-query-cache).
 
-Integrating with Server Side routers and frameworks is very similar to what we just saw, with the addition that the data has to passed from the server to the client to be hydrated into the cache there. To learn how, continue on to the [Server Rendering & Hydration guide](./ssr.md).
+Integrating with Server Side routers and frameworks is very similar to what we just saw, with the addition that the data has to be passed from the server to the client to be hydrated into the cache there. To learn how, continue on to the [Server Rendering & Hydration guide](./ssr.md).
 
 [//]: # 'Materials'

docs/framework/react/guides/scroll-restoration.md

@@ -5,4 +5,6 @@ title: Scroll Restoration
 
 Traditionally, when you navigate to a previously visited page on a web browser, you would find that the page would be scrolled to the exact position where you were before you navigated away from that page. This is called **scroll restoration** and has been in a bit of a regression since web applications have started moving towards client side data fetching. With TanStack Query however, that's no longer the case.
 
+TanStack Query doesn’t implement scroll restoration by itself, but it removes one of the biggest causes of broken restoration in SPA’s: refetch-induced UI resets. By keeping previously fetched data in cache (and optionally using `placeholderData`), navigation back to a page can render instantly with stable layout, making scroll restoration reliable when handled by the router (e.g. React Router’s ScrollRestoration, TanStack Router’s scroll restoration, or a small custom history-based solution).
+
 Out of the box, "scroll restoration" for all queries (including paginated and infinite queries) Just Works™️ in TanStack Query. The reason for this is that query results are cached and able to be retrieved synchronously when a query is rendered. As long as your queries are being cached long enough (the default time is 5 minutes) and have not been garbage collected, scroll restoration will work out of the box all the time.

docs/framework/react/reference/useMutation.md

@@ -64,7 +64,7 @@ mutate(variables, {
   - Optional
   - defaults to `'online'`
   - see [Network Mode](../guides/network-mode.md) for more information.
-- `onMutate: (variables: TVariables) => Promise<TOnMutateResult | void> | TOnMutateResult | void`
+- `onMutate: (variables: TVariables, context: MutationFunctionContext) => Promise<TOnMutateResult | void> | TOnMutateResult | void`
   - Optional
   - This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
   - Useful to perform optimistic updates to a resource in hopes that the mutation succeeds

examples/angular/auto-refetching/package.json

@@ -13,7 +13,7 @@
     "@angular/compiler": "^20.0.0",
     "@angular/core": "^20.0.0",
     "@angular/platform-browser": "^20.0.0",
-    "@tanstack/angular-query-experimental": "^5.90.16",
+    "@tanstack/angular-query-experimental": "^5.90.19",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "0.15.0"