createUseAsyncData options
createUseAsyncData accepts all the same options as useAsyncData, including: server, lazy, immediate, default, transform, pick, getCachedData, deep, dedupe, timeout, and watch.
composable signatures & options
51 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
createUseAsyncData default mode with plain object
When you pass a plain object to createUseAsyncData, the factory options act as defaults. Callers can override any option when invoking the resulting composable.
createUseAsyncData override mode with function
When you pass a function to createUseAsyncData, the factory options override the caller's options. The function receives the caller's options as its argument and returns Partial<AsyncDataOptions>, allowing you to enforce certain options that cannot be overridden.
createUseAsyncData example with getCachedData
Example showing createUseAsyncData usage: export const useCachedData = createUseAsyncData({ getCachedData (key, nuxtApp) { return nuxtApp.payload.data[key] ?? nuxtApp.static.data[key] } }). Then in pages: const { data: mountains } = await useCachedData('mountains', () => $fetch('https://api.nuxtjs.dev/mountains')).
createUseAsyncData signature and behavior
createUseAsyncData is a factory function that creates a custom useAsyncData composable with pre-defined default options. It has two overloaded signatures: function createUseAsyncData(options?: Partial<AsyncDataOptions>): typeof useAsyncData and function createUseAsyncData(options: (callerOptions: AsyncDataOptions) => Partial<AsyncDataOptions>): typeof useAsyncData. The resulting composable is fully typed and works exactly like useAsyncData, but with your defaults baked in.
createUseAsyncData example with defaults override
Example showing default mode: export const useLazyData = createUseAsyncData({ lazy: true, server: false }). Callers can use defaults with const { data } = await useLazyData('key', () => fetchSomeData()) or override with const { data } = await useLazyData('key', () => fetchSomeData(), { server: true }).
createUseAsyncData example with override mode
Example showing override mode: export const useStrictData = createUseAsyncData(callerOptions => ({ deep: false })). In this mode, deep is always enforced as false and cannot be overridden by callers.
createUseAsyncData compiler macro requirement
createUseAsyncData is a compiler macro that must be used as an exported declaration in the composables/ directory or any directory scanned by the Nuxt compiler. Nuxt automatically injects de-duplication keys at build time.
createUseFetch routes declaration does not affect app routes
Routes declared in createUseFetch are only for the composable. They are not added to the app's route set, so plain $fetch and useFetch are unaffected, and a custom createUseFetch client will not accept the app's own server paths.
createUseFetch typed third-party API example
Example showing how to type a third-party API with createUseFetch: import type { DynamicParam, Endpoint } from 'nuxt/app' interface Pet { id: number, name: string } interface PetStoreRoutes { '/pets': { [Endpoint]: { GET: { response: Pet[], query: { limit?: number } } POST: { response: Pet, body: { name: string } } } [DynamicParam]: { [Endpoint]: { GET: { response: Pet } } } } } export const usePetStore = createUseFetch({ baseURL: 'https://api.example.com', routes: {} as PetStoreRoutes, })
createUseFetch signature
createUseFetch is a factory function with three overloads: (1) function createUseFetch(options?: Partial<UseFetchOptions>): typeof useFetch; (2) function createUseFetch(options: (callerOptions: UseFetchOptions) => Partial<UseFetchOptions>): typeof useFetch; (3) function createUseFetch<Routes>(options: Partial<UseFetchOptions> & { routes: Routes }): DeclaredUseFetch<Routes>. It must be used as an exported declaration in the composables/ directory.
createUseFetch with routes parameter for third-party API typing
Pass a routes parameter to createUseFetch to type requests to a third-party API. The routes parameter accepts an interface describing the API's endpoints, methods, query parameters, request bodies, and response types. Only the type of routes is read; the value is dropped before the request is made. Pass routes as {} as Routes syntax. Declared paths are matched as written and should not be prefixed with the baseURL.
createUseFetch routes type structure
The routes interface for createUseFetch uses DynamicParam and Endpoint types from 'nuxt/app'. Routes are structured as a nested object where each path maps to an Endpoint object containing HTTP methods (GET, POST, etc.), each with response, query, and body type definitions. Dynamic path parameters are handled with [DynamicParam]: { [Endpoint]: {...} } syntax.
createUseFetch with custom $fetch instance
You can pass a custom $fetch instance to createUseFetch by using the function signature (override mode). The function must call useNuxtApp() in the setup context rather than module scope to access the Nuxt instance. Example: export const useAPI = createUseFetch(callerOptions => ({ $fetch: useNuxtApp().$api as typeof $fetch, ...callerOptions })).
createUseFetch is a compiler macro
createUseFetch is a compiler macro that must be used as an exported declaration in the composables/ directory or any directory scanned by the Nuxt compiler. Nuxt automatically injects de-duplication keys at build time.
createUseFetch default mode behavior
When createUseFetch receives a plain object, the factory options act as defaults. Callers can override any option when calling the resulting composable. For example, if baseURL is set to 'https://api.nuxt.com' in the factory, a caller can still override it with a different baseURL.
createUseFetch override mode behavior
When createUseFetch receives a function, the factory options override the caller's options. The function receives the caller's options as its argument, allowing you to read them to compute your overrides. Factory options set in override mode cannot be changed by the caller, useful for enforcing settings like authentication headers or a specific base URL.
createUseFetch supported options
createUseFetch accepts all the same options as useFetch, including baseURL, headers, query, onRequest, onResponse, server, lazy, transform, getCachedData, and more. The full list of options is available in the useFetch documentation.
createUseFetch minimal version requirement
createUseFetch requires Nuxt version 4.2 or later.
createUseFetch basic usage example
export const useAPI = createUseFetch({ baseURL: 'https://api.nuxt.com' }). Then in a component: const { data: modules } = await useAPI('/modules'). The resulting useAPI composable has the same signature and return type as useFetch with all options available for the caller to use or override.
useNuxtData signature and return type
useNuxtData is a composable with the signature: export function useNuxtData<DataT = any> (key: string): { data: Ref<DataT | undefined> }. It takes a key parameter as a string that identifies the cached data, and returns an object containing a data property which is a reactive Ref to the cached data of type DataT or undefined if no cached data exists.
useCookie dynamic expiration with getter example
```vue <script setup lang="ts"> const token = useCookie('token', { // Re-evaluated on every write — keep this getter pure expires: () => new Date(Date.now() + 60 * 60 * 1000), // 1 hour from now }) // Assigning a new value also refreshes the cookie expiration token.value = 'new-token' </script> ``` This example demonstrates using a function for the expires option to provide a fresh expiration date every time the cookie is written, useful for sliding sessions or tokens.
useCookie in API routes with getCookie and setCookie
```ts export default defineEventHandler((event) => { // Read counter cookie let counter = getCookie(event, 'counter') || 0 // Increase counter cookie by 1 setCookie(event, 'counter', ++counter) // Send JSON response return { counter } }) ``` You can use getCookie and setCookie from the h3 package to set cookies in server API routes.
useCookie expires option
The expires option has type Date | (() => Date | undefined) with default value undefined. It sets the expiration date for the cookie, or a getter that returns one. When a function is provided, it is evaluated on every cookie write, so expiration can be refreshed when the value is re-set. Returning undefined creates a session cookie. The getter should be pure with no side effects. If both expires and maxAge are set, maxAge takes precedence, though not all clients obey this. If neither is set, the cookie is session-only and removed when the user closes their browser.
useCookie signature and return type
useCookie is called with the syntax: const cookie = useCookie(name, options). It accepts a name parameter (string) and optional CookieOptions object, and returns a CookieRef<T> which extends Vue Ref<T>. The function is SSR-friendly and only works within the Nuxt context. The returned ref automatically serializes and deserializes cookie values to JSON.
useCookie generic type signature
export function useCookie<T = string | null | undefined> (name: string, options?: CookieOptions<T>,): CookieRef<T>
CookieOptions interface
export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> { decode?(value: string): T; encode?(value: T): string; default?: () => T | Ref<T>; watch?: boolean | 'shallow'; readonly?: boolean; refresh?: boolean }
useCookie decode option
The decode option is a custom function with signature (value: string) => T. Default is decodeURIComponent + destr. It decodes the cookie value from a string into a JavaScript object or other type. If an error is thrown, the original non-decoded cookie value is returned.
useCookie encode option
The encode option is a custom function with signature (value: T) => string. Default is JSON.stringify + encodeURIComponent. It encodes a value into a string suited for a cookie's value.
useCookie default option
The default option has type () => T | Ref<T> with default value undefined. It is a function that returns the default value if the cookie does not exist. The function can also return a Ref.
useCookie watch option
The watch option has type boolean | 'shallow' with default value true. When true, enables deep watch for changes and updates the cookie. When 'shallow', enables shallow watch for top-level properties only. When false, disables watching. Note: Refresh useCookie values manually when a cookie has changed with refreshCookie.
useCookie refresh option
The refresh option has type boolean with default value false. If true, the cookie expiration will be refreshed on every explicit write (e.g. cookie.value = cookie.value), even if the value itself hasn't changed. The expiration is not refreshed automatically; you must assign to .value to trigger it. Available since v4.4.
useCookie readonly option
The readonly option has type boolean with default value false. If true, disables writing to the cookie on both server and client. A default value is still returned by the composable but is never persisted to the browser.
useCookie maxAge option
The maxAge option has type number with default value undefined. It sets the max age in seconds for the cookie (the Max-Age Set-Cookie attribute). The given number is converted to an integer by rounding down. By default, no maximum age is set.
useCookie httpOnly option
The httpOnly option has type boolean with default value false. It sets the HttpOnly attribute. Be careful when setting to true, as compliant clients will not allow client-side JavaScript to see the cookie in document.cookie.
useCookie secure option
The secure option has type boolean with default value false. It sets the Secure Set-Cookie attribute. Be careful when setting to true, as compliant clients will not send the cookie back to the server if the browser does not have an HTTPS connection, which can lead to hydration errors.
useCookie partitioned option
The partitioned option has type boolean with default value false. It sets the Partitioned Set-Cookie attribute. This is an attribute that has not yet been fully standardized and may change in the future. Many clients may ignore this attribute until they understand it. See the CHIPS proposal for more information.
useCookie domain option
The domain option has type string with default value undefined. It sets the Domain Set-Cookie attribute. By default, no domain is set, and most clients will consider applying the cookie only to the current domain.
useCookie path option
The path option has type string with default value '/'. It sets the Path Set-Cookie attribute. By default, the path is considered the default path per RFC 6265.
useCookie sameSite option
The sameSite option has type boolean | string with default value undefined. It sets the SameSite Set-Cookie attribute. true sets to Strict, false does not set the attribute, 'lax' sets to Lax, 'none' sets to None for cross-site cookie, 'strict' sets to Strict.
useCookie basic usage example
```vue <script setup lang="ts"> const counter = useCookie('counter') counter.value ||= Math.round(Math.random() * 1000) </script> <template> <div> <h1>Counter: {{ counter || '-' }}</h1> <button @click="counter = null"> reset </button> <button @click="counter--"> - </button> <button @click="counter++"> + </button> </div> </template> ``` This example creates a cookie called counter. If the cookie doesn't exist, it is initially set to a random value. Whenever the counter variable is updated, the cookie is updated accordingly.
useCookie readonly cookies example
```vue <script setup lang="ts"> const user = useCookie( 'userInfo', { default: () => ({ score: -1 }), watch: false, }, ) if (user.value) { // the actual `userInfo` cookie will not be updated user.value.score++ } </script> <template> <div>User score: {{ user?.score }}</div> </template> ``` This example demonstrates using watch: false to prevent cookie updates when the object's properties change.
useCookie shallow watch example
```vue <script setup lang="ts"> const list = useCookie( 'list', { default: () => [], watch: 'shallow', }, ) function add () { list.value?.push(Math.round(Math.random() * 1000)) // list cookie won't be updated with this change } function save () { // the actual `list` cookie will be updated list.value &&= [...list.value] } </script> <template> <div> <h1>List</h1> <pre>{{ list }}</pre> <button @click="add"> Add </button> <button @click="save"> Save </button> </div> </template> ``` This example demonstrates shallow watch mode where top-level property changes are watched, but array mutations do not trigger updates. The cookie is updated only when the entire value is replaced.
useCookie refresh option example
```vue <script setup lang="ts"> const session = useCookie( 'session', { maxAge: 60 * 60, // 1 hour refresh: true, default: () => 'active', }) // Even if the value does not change, // the cookie expiration will be refreshed // every time the setter is called session.value = 'active' </script> <template> <div>Session: {{ session }}</div> </template> ``` This example demonstrates the refresh option, which causes the cookie expiration to be refreshed on every setter call, even if the value hasn't changed.
useLazyFetch composable signature
useLazyFetch has the signature: export function useLazyFetch<ResT, ErrorT = NuxtError<unknown>, DataT = ResT>(url: string | Request | Ref<string | Request> | (() => string | Request), options?: UseFetchOptions<ResT, DataT>): AsyncData<DataT, ErrorT> & Promise<AsyncData<DataT, ErrorT>>. It is equivalent to useFetch with the lazy: true option automatically set.
useLazyFetch parameters
useLazyFetch accepts two parameters: (1) URL as string | Request | Ref<string | Request> | (() => string | Request), which is the URL or request to fetch, and (2) options as an object with the same structure as useFetch options, with the lazy option automatically set to true.
useLazyFetch return values
useLazyFetch returns an AsyncData object with the following properties: data (Ref<DataT | undefined>) - the result of the asynchronous fetch; refresh ((opts?: AsyncDataExecuteOptions) => Promise<void>) - function to manually refresh the data; execute ((opts?: AsyncDataExecuteOptions) => Promise<void>) - alias for refresh; error (Ref<ErrorT | undefined>) - error object if data fetching failed; status (Ref<'idle' | 'pending' | 'success' | 'error'>) - status of the data request; pending (Ref<boolean>) - true while a request is in flight; clear (() => void) - resets data to undefined, error to undefined, sets status to idle, and cancels any pending requests.
useLazyAsyncData signature
useLazyAsyncData has two overloads: function useLazyAsyncData<ResT, DataE = unknown, DataT = ResT>(handler: AsyncDataHandler<ResT>, options?: AsyncDataOptions<ResT, DataT>): AsyncData<DataT, DataE> & Promise<AsyncData<DataT, DataE>> and function useLazyAsyncData<ResT, DataE = unknown, DataT = ResT>(key: MaybeRefOrGetter<string>, handler: AsyncDataHandler<ResT>, options?: AsyncDataOptions<ResT, DataT>): AsyncData<DataT, DataE> & Promise<AsyncData<DataT, DataE>>. It has the same signature as useAsyncData.
useLazyAsyncData lazy option
useLazyAsyncData automatically sets the lazy option to true. The caller does not need to specify this option when using useLazyAsyncData.
useLazyAsyncData parameters and return values
useLazyAsyncData accepts the same parameters as useAsyncData, with the lazy option automatically set to true. It returns the same values as useAsyncData, which include status, data, and other properties from the AsyncData type.
useState signature and parameters
useState is a composable that creates a reactive and SSR-friendly shared state. It has two overloads: export function useState<T> (init?: () => T | Ref<T>): Ref<T> and export function useState<T> (key: string, init?: () => T | Ref<T>): Ref<T>. The key parameter is a unique string ensuring data fetching is properly de-duplicated across requests; if not provided, a key unique to the file and line number of the instance is generated automatically. The init parameter is a function that provides the initial value for the state when not initiated; this function can return a Ref. The generic type parameter T allows specifying the type of state.