Skip to content

docs: Document possible conflict between PersistQueryClientProvider and SSR streaming #9979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ofek-frame wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: Document possible conflict between PersistQueryClientProvider and SSR streaming #9979

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
82b3528
Add docs about PersistQueryClientProvider settings
ofek-frame Dec 17, 2025
c7b108e
correct
ofek-frame Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/framework/react/guides/advanced-ssr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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`
Expand Down