From 91c1ce6afc9d148efdb8d33a807dad1791704d82 Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Wed, 23 Mar 2022 19:16:27 -0400 Subject: [PATCH 1/2] [18] Add docs for useSyncExternalStore --- content/docs/hooks-reference.md | 40 ++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md index fc24b70bf9f..4e9d6172f80 100644 --- a/content/docs/hooks-reference.md +++ b/content/docs/hooks-reference.md @@ -550,14 +550,48 @@ The following Hooks are provided for library authors to integrate libraries deep ### `useSyncExternalStore` {#usesyncexternalstore} ```js -const state = useSyncExternalStore(subscribe, snapshot); +const state = useSyncExternalStore(subscribe, getSnapshot[, getServerSnapshot]); ``` -TODO: description +`useSyncExternalStore` is a hook recommended for reading and subscribing from external data sources in a way that's compatible with concurrent rendering features like selective hydration and time slicing. + +This method returns the value of the store and accepts three arguments: +- `subscribe`: function to register a callback that is called whenever the store changes. +- `getSnapshot`: function that returns the current value of the store. +- `getServerSnapshot` (optional): function that returns the snapshot used during server rendering. + +The most basic example simply subscribes to the entire store: + +```js +const state = useSyncExternalStore(store.subscribe, store.getSnapshot); +``` + +However, you can also subscribe to a specific field: + +```js +const selectedField = useSyncExternalStore( + store.subscribe, + () => store.getSnapshot().selectedField, +); +``` + +When server rendering, you must serialize the store value used on the server, and provide it to `useSyncExternalStore`. React will use this snapshot during hydration to prevent server mismatches: + +```js +const selectedField = useSyncExternalStore( + store.subscribe, + () => store.getSnapshot().selectedField, + () => INITIAL_SERVER_SNAPSHOT.selectedField, +); +``` > Note: > -> TODO: use-sync-external-store/shim +> `getSnapshot` must return a cached value. If getSnapshot is called multiple times in a row, it must return the same exact value unless there was a store update in between. +> +> A shim is provided for supporting multiple React versions published as `use-sync-external-store/shim`. This shim will prefer `useSyncExternalStore` when available, and fallback to a user-space implementation when it's not. +> +> As a convenience, we also provide a version of the API with automatic support for memoizing the result of getSnapshot published as `use-sync-external-store/with-selector`. ### `useInsertionEffect` {#useinsertioneffect} From e0519aee9ef193cc732c10e76fe707a0adf8f499 Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Wed, 23 Mar 2022 19:30:42 -0400 Subject: [PATCH 2/2] rm "optional" --- content/docs/hooks-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/hooks-reference.md b/content/docs/hooks-reference.md index 4e9d6172f80..a6fd4c9f2d8 100644 --- a/content/docs/hooks-reference.md +++ b/content/docs/hooks-reference.md @@ -558,7 +558,7 @@ const state = useSyncExternalStore(subscribe, getSnapshot[, getServerSnapshot]); This method returns the value of the store and accepts three arguments: - `subscribe`: function to register a callback that is called whenever the store changes. - `getSnapshot`: function that returns the current value of the store. -- `getServerSnapshot` (optional): function that returns the snapshot used during server rendering. +- `getServerSnapshot`: function that returns the snapshot used during server rendering. The most basic example simply subscribes to the entire store: