From 82b35285c8b401af17b625ca3822640c8571ecf6 Mon Sep 17 00:00:00 2001
From: Ofek Lavie <ofek@frame.security>
Date: Wed, 17 Dec 2025 15:33:12 +0200
Subject: [PATCH 1/2] Add docs about PersistQueryClientProvider settings

---
 docs/framework/react/guides/advanced-ssr.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/framework/react/guides/advanced-ssr.md b/docs/framework/react/guides/advanced-ssr.md
index db9db2f9a2..c028da7d8d 100644
--- a/docs/framework/react/guides/advanced-ssr.md
+++ b/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 streaming Server Components, 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 settled queries:
+
+```tsx
+<PersistQueryClientProvider
+  client={queryClient}
+  persistOptions={{
+    persister,
+    // We don't want to save promises into the storage, so we only persist settled queries
+    dehydrateOptions: { shouldDehydrateQuery: defaultShouldDehydrateQuery },
+  }}
+>
+  {children}
+</PersistQueryClientProvider>
+```
+
+This ensures that only successfully resolved or errored 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`

From c7b108ee12d6842ec6a052eb085a2167b2e5b5db Mon Sep 17 00:00:00 2001
From: Ofek Lavie <ofek@frame.security>
Date: Wed, 17 Dec 2025 15:39:13 +0200
Subject: [PATCH 2/2] correct

---
 docs/framework/react/guides/advanced-ssr.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/framework/react/guides/advanced-ssr.md b/docs/framework/react/guides/advanced-ssr.md
index c028da7d8d..9431be02e8 100644
--- a/docs/framework/react/guides/advanced-ssr.md
+++ b/docs/framework/react/guides/advanced-ssr.md
@@ -534,7 +534,7 @@ For more information, check out the [Next.js App with Prefetching Example](../ex
 
 ### Using the Persist Adapter with Streaming
 
-If you're using the persist adapter with streaming Server Components, 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 settled queries:
+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 settled queries:
 
 ```tsx
 <PersistQueryClientProvider