docs(ssr): add experimental app directory guide

docs/react/guides/ssr.md

@@ -18,7 +18,9 @@ The exact implementation of these mechanisms may vary from platform to platform,
 - Static Generation (SSG)
 - Server-side Rendering (SSR)
 
-React Query supports both of these forms of pre-rendering regardless of what platform you may be using
+React Query supports both of these forms of pre-rendering regardless of what platform you may be using.
+
+> Note: For notes about how to integrate with the new beta `/app`-folder in Next.js, see further down in this guide.
 
 ### Using `initialData`
 
@@ -59,7 +61,11 @@ To support caching queries on the server and set up hydration:
 
 ```tsx
 // _app.jsx
-import { Hydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  Hydrate,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
 
 export default function MyApp({ Component, pageProps }) {
   const [queryClient] = React.useState(() => new QueryClient())
@@ -82,7 +88,7 @@ Now you are ready to prefetch some data in your pages with either [`getStaticPro
 
 ```tsx
 // pages/posts.jsx
-import { dehydrate, QueryClient, useQuery } from '@tanstack/react-query';
+import { dehydrate, QueryClient, useQuery } from '@tanstack/react-query'
 
 export async function getStaticProps() {
   const queryClient = new QueryClient()
@@ -103,7 +109,10 @@ function Posts() {
 
   // This query was not prefetched on the server and will not start
   // fetching until on the client, both patterns are fine to mix
-  const { data: otherData } = useQuery({ queryKey: ['posts-2'], queryFn: getPosts })
+  const { data: otherData } = useQuery({
+    queryKey: ['posts-2'],
+    queryFn: getPosts,
+  })
 
   // ...
 }
@@ -169,7 +178,11 @@ yarn add use-dehydrated-state
 
 ```tsx
 // root.tsx
-import { Hydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  Hydrate,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
 
 import { useDehydratedState } from 'use-dehydrated-state'
 
@@ -196,7 +209,7 @@ Now you are ready to prefetch some data in your [`loader`](https://remix.run/doc
 
 ```tsx
 // pages/posts.tsx
-import { dehydrate, QueryClient, useQuery } from '@tanstack/react-query';
+import { dehydrate, QueryClient, useQuery } from '@tanstack/react-query'
 
 export async function loader() {
   const queryClient = new QueryClient()
@@ -213,7 +226,10 @@ function Posts() {
 
   // This query was not prefetched on the server and will not start
   // fetching until on the client, both patterns are fine to mix
-  const { data: otherData } = useQuery({ queryKey: ['posts-2'], queryFn: getPosts })
+  const { data: otherData } = useQuery({
+    queryKey: ['posts-2'],
+    queryFn: getPosts,
+  })
 
   // ...
 }
@@ -239,9 +255,14 @@ This guide is at-best, a high level overview of how SSR with React Query should
 > SECURITY NOTE: Serializing data with `JSON.stringify` can put you at risk for XSS-vulnerabilities, [this blog post explains why and how to solve it](https://medium.com/node-security/the-most-common-xss-vulnerability-in-react-js-applications-2bdffbcc1fa0)
 
 ```tsx
-import { dehydrate, Hydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query';
-
-async function handleRequest (req, res) {
+import {
+  dehydrate,
+  Hydrate,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+
+async function handleRequest(req, res) {
   const queryClient = new QueryClient()
   await queryClient.prefetchQuery(['key'], fn)
   const dehydratedState = dehydrate(queryClient)
@@ -251,7 +272,7 @@ async function handleRequest (req, res) {
       <Hydrate state={dehydratedState}>
         <App />
       </Hydrate>
-    </QueryClientProvider>
+    </QueryClientProvider>,
   )
 
   res.send(`
@@ -276,7 +297,11 @@ async function handleRequest (req, res) {
 - Render your app with the client provider and also **using the dehydrated state. This is extremely important! You must render both server and client using the same dehydrated state to ensure hydration on the client produces the exact same markup as the server.**
 
 ```tsx
-import { Hydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  Hydrate,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
 
 const dehydratedState = window.__REACT_QUERY_STATE__
 
@@ -288,40 +313,200 @@ ReactDOM.hydrate(
       <App />
     </Hydrate>
   </QueryClientProvider>,
-  document.getElementById('root')
+  document.getElementById('root'),
 )
 ```
 
+## Using Experimental `app` Directory in Next.js 13
+
+> **WARNING:** The `app` directory introduced in Next.js 13 is currently in beta, and it is not recommended for use in production. The API is not stable.
+>
+> This guide is provided as is to supply a quick start for early exploration of Next.js 13's experimental features and does not represent the final APIs.
+
+Both prefetching approaches, using `initialData` or `<Hydrate>`, are available within the `app` directory.
+
+- Prefetch the data in a Server Component and prop drill `initialData` to Client Components
+  - Quick to set up for simple cases
+  - May need to prop drill through multiple layers of Client Components
+  - May need to prop drill to multiple Client Components using the same query
+  - Query refetching is based on when the page loads instead of when the data was prefetched on the server
+- Prefetch the query on the server, dehydrate the cache and rehydrate it on the client with `<Hydrate>`
+  - Requires slightly more setup up front
+  - No need to prop drill
+  - Query refetching is based on when the query was prefetched on the server
+
+### `<QueryClientProvider>` is required by both the `initialData` and `<Hydrate>` prefetching approaches
+
+The hooks provided by the `react-query` package need to retrieve a `QueryClient` from their context. Wrap your component tree with `<QueryClientProvider>` and pass it an instance of `QueryClient`.
+
+```tsx
+// app/providers.jsx
+'use client'
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+export default function Providers({ children }) {
+  const [queryClient] = React.useState(() => new QueryClient())
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  )
+}
+```
+
+```tsx
+// app/layout.jsx
+import Providers from './providers'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <head />
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+### Using `initialData`
+
+Fetch your initial data in a Server Component higher up in the component tree, and pass it to your Client Component as a prop.
+
+```tsx
+// app/page.jsx
+export default async function Home() {
+  const initialData = await getPosts()
+
+  return <Posts posts={initialData} />
+}
+```
+
+```tsx
+// app/posts.jsx
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+
+export function Posts(props) {
+  const { data } = useQuery({
+    queryKey: ['posts'],
+    queryFn: getPosts,
+    initialData: props.posts,
+  })
+
+  // ...
+}
+```
+
+### Using `<Hydrate>`
+
+Create a request-scoped singleton instance of `QueryClient`. **This ensures that data is not shared between different users and requests, while still only creating the QueryClient once per request.**
+
+```tsx
+// app/getQueryClient.jsx
+import { QueryClient } from '@tanstack/react-query'
+import { cache } from 'react'
+
+const getQueryClient = cache(() => new QueryClient())
+export default getQueryClient
+```
+
+Fetch your data in a Server Component higher up in the component tree than the Client Components that use the prefetched queries. Your prefetched queries will be available to all components deeper down the component tree.
+
+- Retrieve the `QueryClient` singleton instance
+- Prefetch the data using the client's prefetchQuery method and wait for it to complete
+- Use `dehydrate` to obtain the dehydrated state of the prefetched queries from the query cache
+- Wrap the component tree that needs the prefetched queries inside `<Hydrate>`, and provide it with the dehydrated state
+- You can fetch inside multiple Server Components and use `<Hydrate>` in multiple places
+
+> NOTE: TypeScript currently complains of a type error when using async Server Components. As a temporary workaround, use `{/* @ts-expect-error Server Component */}` when calling this component inside another. For more information, see [End-to-End Type Safety](https://beta.nextjs.org/docs/configuring/typescript#end-to-end-type-safety) in the Next.js 13 beta docs.
+
+```tsx
+// app/hydratedPosts.jsx
+import { dehydrate, Hydrate } from '@tanstack/react-query'
+import getQueryClient from './getQueryClient'
+
+export default async function HydratedPosts() {
+  const queryClient = getQueryClient()
+  await queryClient.prefetchQuery(['posts'], getPosts)
+  const dehydratedState = dehydrate(queryClient)
+
+  return (
+    <Hydrate state={dehydratedState}>
+      <Posts />
+    </Hydrate>
+  )
+}
+```
+
+During server rendering, calls to `useQuery` nested within the `<Hydrate>` Client Component will have access to prefetched data provided in the state property.
+
+```tsx
+// app/posts.jsx
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+
+export default function Posts() {
+  // This useQuery could just as well happen in some deeper child to
+  // the "HydratedPosts"-component, data will be available immediately either way
+  const { data } = useQuery({ queryKey: ['posts'], queryFn: getPosts })
+
+  // This query was not prefetched on the server and will not start
+  // fetching until on the client, both patterns are fine to mix
+  const { data: otherData } = useQuery({
+    queryKey: ['posts-2'],
+    queryFn: getPosts,
+  })
+
+  // ...
+}
+```
+
+As demonstrated, it's fine to prefetch some queries and let others fetch on the client. This means you can control what content server renders or not by adding or removing `prefetchQuery` for a specific query.
+
+### Streaming, Suspense and server-side fetching
+
+Right now, you always have to `await` the data in the Server Component. In the future, the goal is to be able to _start_ prefetching in a Server Component but not block rendering, instead streaming markup and data to the client incrementally as it gets available. This is currently lacking support in both React and Query.
+
+Similarily, you _must_ currently prefetch the data in a Server Component if you want it to be server rendered. A `useQuery()` call even with the `suspense` option enabled will not fetch data on the server, only on the client. We hope to support this in the future, but exact details are still unknown.
+
 ## Custom SSR with suspense
 
 If you do not want to provide `prefetchQuery()` for all your queries in the SSR you can use suspense.
 
 ### Server
 
 ```tsx
-import { dehydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  dehydrate,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
 import ssrPrepass from 'react-ssr-prepass'
 
-async function handleRequest (req, res) {
+async function handleRequest(req, res) {
   const queryClient = new QueryClient()
 
   // React SSR does not support ErrorBoundary
   try {
     // Traverse the tree and fetch all Suspense data (thrown promises)
-    await ssrPrepass(<App />);
+    await ssrPrepass(<App />)
   } catch (e) {
-    console.error(e);
+    console.error(e)
     // Send the index.html (without SSR) on error, so user can try to recover and see something
-    return res.sendFile('path/to/dist/index.html');
+    return res.sendFile('path/to/dist/index.html')
   }
 
   const html = ReactDOM.renderToString(
     <QueryClientProvider client={queryClient}>
       <App />
-    </QueryClientProvider>
+    </QueryClientProvider>,
   )
 
-  const dehydratedState = dehydrate(queryClient);
+  const dehydratedState = dehydrate(queryClient)
 
   res.send(`
     <html>