Nuxt/docs/3.api/3.utils/call-once.md

title	description	navigation	links
callOnce	Run a given function or block of code once during SSR or CSR.	badge New	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/once.ts xs

::important This utility is available since Nuxt v3.9. ::

::important navigation mode is available since Nuxt v3.15. ::

Purpose

The callOnce function is designed to execute a given function or block of code only once during:

• server-side rendering but not hydration
• client-side navigation

This is useful for code that should be executed only once, such as logging an event or setting up a global state.

Usage

Running code only once. For example, if the code runs on the server it won't run again on the client. this demonstrates the default render mode behaviour.

<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  console.log('This will only be logged once')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>

Sometimes you do want code to run on every navigation - just avoid the initial server/client double load. For this, there's a new mode: navigation option that will run the code only once per navigation.

<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>

::tip{to="/docs/getting-started/state-management#usage-with-pinia"} callOnce is useful in combination with the Pinia module to call store actions. ::

:read-more{to="/docs/getting-started/state-management"}

::warning Note that callOnce doesn't return anything. You should use useAsyncData or useFetch if you want to do data fetching during SSR. ::

::note callOnce is a composable meant to be called directly in a setup function, plugin, or route middleware, because it needs to add data to the Nuxt payload to avoid re-calling the function on the client when the page hydrates. ::

Type

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.
• 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