(docs) - document ssrExchange/next-urql staleWhileRevalidate option (#…

…1853)

* add docs about staleWhileRevalidate

* Apply suggestions from code review

Co-authored-by: Phil Pluckthun <[email protected]>

* Apply suggestions from code review

Co-authored-by: Phil Pluckthun <[email protected]>

Co-authored-by: Phil Pluckthun <[email protected]>

docs/advanced/server-side-rendering.md

@@ -41,6 +41,9 @@ const client = createClient({
 The `ssrExchange` must be initialized with the `isClient` and `initialState` options. The `isClient`
 option tells the exchange whether it's on the server- or client-side. In our example we use `typeof window` to determine this, but in Webpack environments you may also be able to use `process.browser`.
 
+Optionally, we may also choose to enable `staleWhileRevalidate`. When enabled this flag will ensure that although a result may have been rehydrated from our SSR result, another
+refetch `network-only` operation will be issued, to update stale data. This is useful for statically generated sites (SSG) that may ship stale data to our application initially.
+
 The `initialState` option should be set to the serialized data you retrieve on your server-side.
 This data may be retrieved using methods on `ssrExchange()`. You can retrieve the serialized data
 after server-side rendering using `ssr.extractData()`:
@@ -204,7 +207,7 @@ Optimization"](https://nextjs.org/docs/advanced-features/automatic-static-optimi
 // pages/index.js
 import React from 'react';
 import Head from 'next/head';
-import { useQuery } from "urql";
+import { useQuery } from 'urql';
 import { withUrqlClient } from 'next-urql';
 
 const Index = () => {
@@ -305,6 +308,23 @@ The above example will make sure the page is rendered as a static-page, it's imp
 so in our case we were only interested in getting our todos, if there are child components relying on data you'll have to make
 sure these are fetched as well.
 
+### Stale While Revalidate
+
+If we choose to use Next's static site generation (SSG or ISG) we may be embedding data in our initial payload that's stale on the client. In this case, we may want to update this data immediately after rehydration.
+We can pass `staleWhileRevalidate: true` to `withUrqlClient`'s second option argument to Switch it to a mode where it'll refresh its rehydrated data immediately by issuing another network request.
+
+```js
+export default withUrqlClient(
+  ssr => ({
+    url: 'your-url',
+  }),
+  { staleWhileRevalidate: true }
+)(...);
+```
+
+Now, although on rehydration we'll receive the stale data from our `ssrExchange` first, it'll also immediately issue another `network-only` operation to update the data.
+During this revalidation our stale results will be marked using `result.stale`. While this is similar to what we see with `cache-and-network` without server-side rendering, it isn't quite the same. Changing the request policy wouldn't actually refetch our data on rehydration as the `ssrExchange` is simply a replacement of a full network request. Hence, this flag allows us to treat this case separately.
+
 ### Resetting the client instance
 
 In rare scenario's you possibly will have to reset the client instance (reset all cache, ...), this

docs/api/core.md

@@ -280,11 +280,13 @@ The `ssrExchange` as [described on the "Server-side Rendering"
 page.](../advanced/server-side-rendering.md).
 It's of type `Options => Exchange`.
 
-It accepts two inputs, `initialState` which is completely
+It accepts three inputs, `initialState` which is completely
 optional and populates the server-side rendered data with
-a rehydrated cache, and `isClient` which can be set to
+a rehydrated cache, `isClient` which can be set to
 `true` or `false` to tell the `ssrExchange` whether to
-write to (server-side) or read from (client-side) the cache.
+write to (server-side) or read from (client-side) the cache, and
+`staleWhileRevalidate` which will treat rehydrated data as stale
+and refetch up-to-date data by reexecuring the operation using a `network-only` requests policy.
 
 By default, `isClient` defaults to `true` when the `Client.suspense`
 mode is disabled and to `false` when the `Client.suspense` mode