From 2dd767216c081b75b3690c9ee0a37ede7be9749d Mon Sep 17 00:00:00 2001
From: Saeid Zareie <65568529+Saeid-Za@users.noreply.github.com>
Date: Tue, 21 Jan 2025 17:42:52 +0330
Subject: [PATCH] docs: add more context about `navigation` mode in `callOnce`
 composable (#30612)

---
 docs/3.api/3.utils/call-once.md | 36 +++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/docs/3.api/3.utils/call-once.md b/docs/3.api/3.utils/call-once.md
index f3f2b49bc3..35d6c3e957 100644
--- a/docs/3.api/3.utils/call-once.md
+++ b/docs/3.api/3.utils/call-once.md
@@ -24,6 +24,8 @@ This is useful for code that should be executed only once, such as logging an ev
 
 ## Usage
 
+The default mode of `callOnce` is to run code only once. For example, if the code runs on the server it won't run again on the client. It also won't run again if you `callOnce` more than once on the client, for example by navigating back to this page.
+
 ```vue [app.vue]
 <script setup lang="ts">
 const websiteConfig = useState('config')
@@ -35,6 +37,23 @@ await callOnce(async () => {
 </script>
 ```
 
+It is also possible to run on every navigation while still avoiding the initial server/client double load. For this, it is possible to use the `navigation` mode:
+
+```vue [app.vue]
+<script setup lang="ts">
+const websiteConfig = useState('config')
+
+await callOnce(async () => {
+  console.log('This will only be logged once and then on every client side navigation')
+  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
+}, { mode: 'navigation' })
+</script>
+```
+
+::important
+`navigation` mode is available since [Nuxt v3.15](/blog/v3-15).
+::
+
 ::tip{to="/docs/getting-started/state-management#usage-with-pinia"}
 `callOnce` is useful in combination with the [Pinia module](/modules/pinia) to call store actions.
 ::
@@ -52,9 +71,22 @@ Note that `callOnce` doesn't return anything. You should use [`useAsyncData`](/d
 ## Type
 
 ```ts
-callOnce(fn?: () => any | Promise<any>): Promise<void>
-callOnce(key: string, fn?: () => any | Promise<any>): Promise<void>
+callOnce (key?: string, fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
+callOnce(fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
+
+type CallOnceOptions = {
+  /**
+   * Execution mode for the callOnce function
+   * @default 'render'
+   */
+  mode?: 'navigation' | 'render'
+}
 ```
 
+## Parameters
+
 - `key`: A unique key ensuring that the code is run once. If you do not provide a key, then a key that is unique to the file and line number of the instance of `callOnce` will be generated for you.
 - `fn`: The function to run once. This function can also return a `Promise` and a value.
+- `options`: Setup the mode, either to re-execute on navigation (`navigation`) or just once for the lifetime of the app (`render`). Defaults to `render`.
+  - `render`: Executes once during initial render (either SSR or CSR) - Default mode
+  - `navigation`: Executes once during initial render and once per subsequent client-side navigation