docs: add note about fetching data on initial load

nuxt · pi0 · Sep 3, 2022 · Aug 31, 2022 · Sep 1, 2022 · Sep 3, 2022
commit 15a593d1ba3372851cade3dd774eb53368334af4
diff --git a/docs/content/3.api/1.composables/use-async-data.md b/docs/content/3.api/1.composables/use-async-data.md
@@ -38,7 +38,7 @@ type AsyncData<DataT> = {
 * **key**: a unique key to ensure that data fetching can be properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.
 * **handler**: an asynchronous function that returns a value
 * **options**:
-  * _lazy_: whether to resolve the async function after loading the route, instead of blocking navigation (defaults to `false`)
+  * _lazy_: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`)
   * _default_: a factory function to set the default value of the data, before the async function resolves - particularly useful with the `lazy: true` option
   * _server_: whether to fetch the data on the server (defaults to `true`)
   * _transform_: a function that can be used to alter `handler` function result after resolving
@@ -55,7 +55,11 @@ Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the rout
 * **refresh**: a function that can be used to refresh the data returned by the `handler` function
 * **error**: an error object if the data fetching failed
 
-By default, Nuxt waits until a `refresh` is finished before it can be executed again. Passing `true` as parameter skips that wait.
+By default, Nuxt waits until a `refresh` is finished before it can be executed again.
+
+::alert{type=warning}
+If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await `useAsyncData` on client-side, `data` will remain null within `<script setup>`.
+::
 
 ## Example
 

diff --git a/docs/content/3.api/1.composables/use-fetch.md b/docs/content/3.api/1.composables/use-fetch.md
@@ -45,7 +45,7 @@ type AsyncData<DataT> = {
   * `baseURL`: Base URL for the request.
 * **Options (from `useAsyncData`)**:
   * `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests, if not provided, it will be generated based on the `url` and fetch options.
-  * `lazy`: Whether to resolve the async function after loading the route, instead of blocking navigation (defaults to `false`).
+  * `lazy`: Whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`).
   * `server`: Whether to fetch the data on the server (defaults to `true`).
   * `default`: A factory function to set the default value of the data, before the async function resolves - particularly useful with the `lazy: true` option.
   * `pick`: Only pick specified keys in this array from the `handler` function result.
@@ -64,7 +64,11 @@ If you provide a function or ref as the `url` parameter, or if you provide funct
 * **refresh**: a function that can be used to refresh the data returned by the `handler` function.
 * **error**: an error object if the data fetching failed.
 
-By default, Nuxt waits until a `refresh` is finished before it can be executed again. Passing `true` as parameter skips that wait.
+By default, Nuxt waits until a `refresh` is finished before it can be executed again.
+
+::alert{type=warning}
+If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.
+::
 
 ## Example