📝 Update various ssr/rehydration documentation

reduxjs · Oct 26, 2021 · f17724e · f17724e
1 parent 32c82c5
commit f17724e
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 9 deletions.
diff --git a/docs/rtk-query/api/created-api/miscellaneous-utils.mdx b/docs/rtk-query/api/created-api/miscellaneous-utils.mdx
@@ -24,7 +24,7 @@ Each API slice object has `getRunningOperationPromises` and `getRunningOperation
 #### Signature
 
 ```ts no-transpile
-const getRunningOperationPromises: () => Array<Promise<unknown>>
+getRunningOperationPromises: () => Array<Promise<unknown>>
 ```
 
 #### Description
@@ -43,11 +43,17 @@ await Promise.all(api.getRunningOperationPromises())
 #### Signature
 
 ```ts no-transpile
-const getRunningOperationPromise: <EndpointName extends QueryKeys<Definitions>>(
+getRunningOperationPromise: <EndpointName extends QueryKeys<Definitions>>(
   endpointName: EndpointName,
   args: QueryArgFrom<Definitions[EndpointName]>
 ) =>
   | QueryActionCreatorResult<Definitions[EndpointName]>
+  | undefined
+
+getRunningOperationPromise: <EndpointName extends MutationKeys<Definitions>>(
+  endpointName: EndpointName,
+  fixedCacheKeyOrRequestId: string
+) =>
   | MutationActionCreatorResult<Definitions[EndpointName]>
   | undefined
 ```
@@ -57,5 +63,6 @@ const getRunningOperationPromise: <EndpointName extends QueryKeys<Definitions>>(
 A function that returns a single promise for a given endpoint name + argument combination,
 if it is currently running. If it is not currently running, the function returns `undefined`.
 
-This enables writing custom hooks that look up if RTK Query has already got a running promise
+This is primarily added to add experimental support for suspense in the future.
+It enables writing custom hooks that look up if RTK Query has already got a running promise
 for a certain endpoint/argument combination, and retrieving that promise to `throw` it.
diff --git a/docs/rtk-query/usage/persistence-and-rehydration.mdx b/docs/rtk-query/usage/persistence-and-rehydration.mdx
@@ -17,12 +17,24 @@ for fulfilled & errored queries.
 
 See also [Server Side Rendering](./server-side-rendering.mdx).
 
+:::info
+
+Generally, persisting API slices is not recommended and instead, mechanisms like
+[`Cache-Control` Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
+should be used in browsers to define cache behaviour.
+Persisting and rehydrating an api slice might always leave the user with very stale data if the user
+has not visited the page for some time.
+Nonetheless, in environments like Native Apps, where there is no browser cache to take care of this,
+persistance might still be a viable option.
+
+:::
+
 ## Redux Persist
 
 API state rehydration can be used in conjunction with [Redux Persist](https://github.com/rt2zz/redux-persist)
 by leveraging the `REHYDRATE` action type imported from `redux-persist`. This can be used out of the
-box with the `autoMergeLevel1` or `autoMergeLevel2` [state reconcilers](https://github.com/rt2zz/redux-persist#state-reconciler),
-but not with the `hardSet` reconciler.
+box with the `autoMergeLevel1` or `autoMergeLevel2` [state reconcilers](https://github.com/rt2zz/redux-persist#state-reconciler)
+when persisting the root reducer, or with the `autoMergeLevel1` reconciler when persisting just the api reducer.
 
 ```ts title="redux-persist rehydration example"
 import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

diff --git a/docs/rtk-query/usage/server-side-rendering.mdx b/docs/rtk-query/usage/server-side-rendering.mdx
@@ -26,20 +26,28 @@ The workflow is as follows:
 
   [examples](docblock://query/createApi.ts?token=CreateApiOptions.extractRehydrationInfo)
 
+An example repo using `next.js` is available [here](https://github.com/phryneas/ssr-experiments/tree/main/nextjs-blog).
+
 :::tip
 While memory leaks are not anticipated, once a render is sent to the client and the store is being
 removed from memory, you may wish to also call `store.dispatch(api.util.resetApiState())` to
 ensure that no rogue timers are left running.
 :::
 
-An example repo using `next.js` is available [here](https://github.com/phryneas/ssr-experiments/tree/main/nextjs-blog).
+:::tip
+In order to avoid providing stale data with Static Site Generation (SSG), you may wish to set
+[`refetchOnMountOrArgChange`](../api/createApi.mdx#refetchonmountorargchange) to a reasonable value
+such as 900 (seconds) in order to allow data to be re-fetched if it has been that long (in seconds) since
+the page was generated.
+:::
 
 ## Server Side Rendering elsewhere
 
 If you are not using `next.js`, and the example above cannot be adapted to your SSR framework,
-an `unstable__` marked approach is available to support SSR scenarios that render the full tree
-multiple times until nothing changes any more. Doing so might require async code to be triggered
-during render and not safely in an effect.
+an `unstable__` marked approach is available to support SSR scenarios where you need to execute
+async code during render and not safely in an effect.
+This is a similar approach to using [`getDataFromTree`](https://www.apollographql.com/docs/react/performance/server-side-rendering/#executing-queries-with-getdatafromtree)
+with [Apollo](https://www.apollographql.com/docs/).
 
 The workflow is as follows: