docs: SSR rewrite (#5966)

* docs(react-query): add Request Waterfalls guide

Also includes initial scaffold for new prefetch/SSR docs structure

* docs(react-query): update prefetching guide

* docs(migration-guide): add more hydration api changes to migration guide

* docs(prefetching): polish prefetching docs

* docs(react-query): rewrite ssr doc page

* docs(react-query): add advanced server rendering guide

* docs(react-query): add clarifications to ssr docs

* docs(react-query): add note about Suspense for streaming ssr plugin

---------

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: Ephem

docs/config.json

@@ -112,10 +112,6 @@
               "label": "Placeholder Query Data",
               "to": "react/guides/placeholder-query-data"
             },
-            {
-              "label": "Prefetching",
-              "to": "react/guides/prefetching"
-            },
             {
               "label": "Mutations",
               "to": "react/guides/mutations"
@@ -149,9 +145,21 @@
               "to": "react/guides/filters"
             },
             {
-              "label": "SSR & Next.js",
+              "label": "Performance & Request Waterfalls",
+              "to": "react/guides/request-waterfalls"
+            },
+            {
+              "label": "Prefetching & Router Integration",
+              "to": "react/guides/prefetching"
+            },
+            {
+              "label": "Server Rendering & Hydration",
               "to": "react/guides/ssr"
             },
+            {
+              "label": "Advanced Server Rendering",
+              "to": "react/guides/advanced-ssr"
+            },
             {
               "label": "Caching",
               "to": "react/guides/caching"

docs/react/guides/advanced-ssr.md

@@ -68,22 +68,28 @@ Dynamic parallel query - `useQueries` can depend on a previous query also, here'
 const { data: userIds } = useQuery({
   queryKey: ['users'],
   queryFn: getUsersData,
-  select: users => users.map(user => user.id),
+  select: (users) => users.map((user) => user.id),
 })
 
 // Then get the users messages
 const usersMessages = useQueries({
   queries: users
-    ? usersId.map(id => {
+    ? usersId.map((id) => {
         return {
           queryKey: ['messages', id],
           queryFn: () => getMessagesByUsers(id),
-        };
+        }
       })
-  : [], // if users is undefined, an empty array will be returned
+    : [], // if users is undefined, an empty array will be returned
 })
 ```
 
 [//]: # 'Example2'
 
 **Note** that `useQueries` return an **array of query results**
+
+## A note about performance
+
+Dependent queries by definition constitutes a form of [request waterfall](../guides/request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible.
+
+In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall.

docs/react/guides/dependent-queries.md

@@ -312,9 +312,9 @@ However, refetching all pages might lead to UI inconsistencies. Also, this optio
 
 The v5 includes a new `maxPages` option for infinite queries to limit the number of pages to store in the query data and to refetch. This new feature handles the use cases initially identified for the `refetchPage` page feature without the related issues.
 
-### New hydration API
+### New `dehydrate` API
 
-The options you can pass to dehydrate have been simplified. Queries and Mutations are always dehydrated (according to the default function implementation). To change this behaviour, you can implement `shouldDehydrateQuery` or `shouldDehydrateMutation`.
+The options you can pass to `dehydrate` have been simplified. Queries and Mutations are always dehydrated (according to the default function implementation). To change this behaviour, instead of using the removed boolean options `dehydrateMutations` and `dehydrateQueries` you can implement the function equivalents `shouldDehydrateQuery` or `shouldDehydrateMutation` instead. To get the old behaviour of not hydrating queries/mutations at all, pass in `() => false`.
 
 ```diff
 - dehydrateMutations?: boolean
@@ -386,9 +386,15 @@ import { batch } from 'solid-js'
 notifyManager.setBatchNotifyFunction(batch)
 ```
 
-### `Hydrate` has been renamed to `HydrationBoundary` and the `useHydrate` hook has been removed
+### Hydration API changes
 
-The `Hydrate` component has been renamed to `HydrationBoundary`. The `Hydrate` component was also a wrapper over `useHydrate` hook, which has been removed.
+To better support concurrent features and transitions we've made some changes to the hydration APIs. The `Hydrate` component has been renamed to `HydrationBoundary` and the `useHydrate` hook has been removed.
+
+The `HydrationBoundary` no longer hydrates mutations, only queries. To hydrate mutations, use the low level `hydrate` API or the `persistQueryClient` plugin.
+
+Finally, as a technical detail, the timing for when queries are hydrated have changed slightly. New queries are still hydrated in the render phase so that SSR works as usual, but any queries that already exist in the cache are now hydrated in an effect instead (as long as their data is fresher than what is in the cache). If you are hydrating just once at the start of your application as is common, this wont affect you, but if you are using Server Components and pass down fresh data for hydration on a page navigation, you might notice a flash of the old data before the page immediately rerenders.
+
+This last change is technically a breaking one, and was made so we don't prematurely update content on the _existing_ page before a page transition has been fully committed. No action is required on your part.
 
 ```diff
 - import { Hydrate } from '@tanstack/react-query'