From 406732ad4422ef8bcaa371b536228c508c10cfb5 Mon Sep 17 00:00:00 2001
From: Camille Coutens <41164034+Kamsou@users.noreply.github.com>
Date: Tue, 14 Jan 2025 15:05:29 +0100
Subject: [PATCH] docs: add context for `useAsyncData` side effects (#30479)

---
 docs/1.getting-started/6.data-fetching.md  | 13 +++++++++++++
 docs/3.api/2.composables/use-async-data.md |  5 ++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/1.getting-started/6.data-fetching.md b/docs/1.getting-started/6.data-fetching.md
index f8c48b3759..c82f5ca2f8 100644
--- a/docs/1.getting-started/6.data-fetching.md
+++ b/docs/1.getting-started/6.data-fetching.md
@@ -202,6 +202,19 @@ const { data: discounts, status } = await useAsyncData('cart-discount', async ()
 </script>
 ```
 
+::note
+`useAsyncData` is for fetching and caching data, not triggering side effects like calling Pinia actions, as this can cause unintended behavior such as repeated executions with nullish values. If you need to trigger side effects, use the [`callOnce`](/docs/api/utils/call-once) utility to do so.
+
+```vue
+<script setup lang="ts">
+const offersStore = useOffersStore()
+
+// you can't do this
+await useAsyncData(() => offersStore.getOffer(route.params.slug))
+</script>
+```
+::
+
 ::read-more{to="/docs/api/composables/use-async-data"}
 Read more about `useAsyncData`.
 ::
diff --git a/docs/3.api/2.composables/use-async-data.md b/docs/3.api/2.composables/use-async-data.md
index 1a297d253f..6f422d19e5 100644
--- a/docs/3.api/2.composables/use-async-data.md
+++ b/docs/3.api/2.composables/use-async-data.md
@@ -62,7 +62,10 @@ const { data: posts } = await useAsyncData(
 ## Params
 
 - `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 must return a truthy value (for example, it should not be `undefined` or `null`) or the request may be duplicated on the client side
+- `handler`: an asynchronous function that must return a truthy value (for example, it should not be `undefined` or `null`) or the request may be duplicated on the client side.
+::warning
+The `handler` function should be **side-effect free** to ensure predictable behavior during SSR and CSR hydration. If you need to trigger side effects, use the [`callOnce`](/docs/api/utils/call-once) utility to do so.
+::
 - `options`:
   - `server`: whether to fetch the data on the server (defaults to `true`)
   - `lazy`: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`)