@nuxt/docs 0.0.0 → 3.17.1

package/3.api/2.composables/use-fetch.md

@@ -0,0 +1,217 @@
+---
+title: 'useFetch'
+description: 'Fetch data from an API endpoint with an SSR-friendly composable.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/fetch.ts
+    size: xs
+---
+
+This composable provides a convenient wrapper around [`useAsyncData`](/docs/api/composables/use-async-data) and [`$fetch`](/docs/api/utils/dollarfetch).
+It automatically generates a key based on URL and fetch options, provides type hints for request url based on server routes, and infers API response type.
+
+::note
+`useFetch` is a composable meant to be called directly in a setup function, plugin, or route middleware. It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client without re-fetching the data on client side when the page hydrates.
+::
+
+## Usage
+
+```vue [pages/modules.vue]
+<script setup lang="ts">
+const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
+  pick: ['title']
+})
+</script>
+```
+
+::warning
+If you're using a custom useFetch wrapper, do not await it in the composable, as that can cause unexpected behavior. Please follow [this recipe](/docs/guide/recipes/custom-usefetch#custom-usefetch) for more information on how to make a custom async data fetcher.
+::
+
+::note
+`data`, `status`, and `error` are Vue refs, and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
+::
+
+Using the `query` option, you can add search parameters to your query. This option is extended from [unjs/ofetch](https://github.com/unjs/ofetch) and is using [unjs/ufo](https://github.com/unjs/ufo) to create the URL. Objects are automatically stringified.
+
+```ts
+const param1 = ref('value1')
+const { data, status, error, refresh } = await useFetch('/api/modules', {
+  query: { param1, param2: 'value2' }
+})
+```
+
+The above example results in `https://api.nuxt.com/modules?param1=value1&param2=value2`.
+
+You can also use [interceptors](https://github.com/unjs/ofetch#%EF%B8%8F-interceptors):
+
+```ts
+const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
+  onRequest({ request, options }) {
+    // Set the request headers
+    // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
+    options.headers.set('Authorization', '...')
+  },
+  onRequestError({ request, options, error }) {
+    // Handle the request errors
+  },
+  onResponse({ request, response, options }) {
+    // Process the response data
+    localStorage.setItem('token', response._data.token)
+  },
+  onResponseError({ request, response, options }) {
+    // Handle the response errors
+  }
+})
+```
+
+### Reactive Keys and Shared State
+
+You can use a computed ref or a plain ref as the URL, allowing for dynamic data fetching that automatically updates when the URL changes:
+
+```vue [pages/[id\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const id = computed(() => route.params.id)
+
+// When the route changes and id updates, the data will be automatically refetched
+const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
+</script>
+```
+
+When using `useFetch` with the same URL and options in multiple components, they will share the same `data`, `error` and `status` refs. This ensures consistency across components.
+
+::warning
+`useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
+::
+
+::warning
+If you encounter the `data` variable destructured from a `useFetch` returns a string and not a JSON parsed object then make sure your component doesn't include an import statement like `import { useFetch } from '@vueuse/core`.
+::
+
+:video-accordion{title="Watch the video from Alexander Lichter to avoid using useFetch the wrong way" videoId="njsGVmcWviY"}
+
+:link-example{to="/docs/examples/advanced/use-custom-fetch-composable"}
+
+:read-more{to="/docs/getting-started/data-fetching"}
+
+:link-example{to="/docs/examples/features/data-fetching"}
+
+## Params
+
+- `URL`: The URL to fetch.
+- `Options` (extends [unjs/ofetch](https://github.com/unjs/ofetch) options & [AsyncDataOptions](/docs/api/composables/use-async-data#params)):
+  - `method`: Request method.
+  - `query`: Adds query search params to URL using [ufo](https://github.com/unjs/ufo)
+  - `params`: Alias for `query`
+  - `body`: Request body - automatically stringified (if an object is passed).
+  - `headers`: Request headers.
+  - `baseURL`: Base URL for the request.
+  - `timeout`: Milliseconds to automatically abort request
+  - `cache`: Handles cache control according to [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/fetch#cache)
+    - You can pass boolean to disable the cache or you can pass one of the following values: `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`.
+
+::note
+All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
+::
+
+- `Options` (from [`useAsyncData`](/docs/api/composables/use-async-data)):
+  - `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests, if not provided, it will be automatically generated based on URL and fetch 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`)
+  - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`)
+  - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option
+  - `transform`: a function that can be used to alter `handler` function result after resolving
+  - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
+    ```ts
+    const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating 
+      ? nuxtApp.payload.data[key] 
+      : nuxtApp.static.data[key]
+    ```
+    Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled.
+  - `pick`: only pick specified keys in this array from the `handler` function result
+  - `watch`: watch an array of reactive sources and auto-refresh the fetch result when they change. Fetch options and URL are watched by default. You can completely ignore reactive sources by using `watch: false`. Together with `immediate: false`, this allows for a fully-manual `useFetch`. (You can [see an example here](/docs/getting-started/data-fetching#watch) of using `watch`.)
+  - `deep`: return data in a deep ref object (it is `true` by default). It can be set to `false` to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive.
+  - `dedupe`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
+    - `cancel` - cancels existing requests when a new one is made
+    - `defer` - does not make new requests at all if there is a pending request
+
+::note
+If you provide a function or ref as the `url` parameter, or if you provide functions as arguments to the `options` parameter, then the `useFetch` call will not match other `useFetch` calls elsewhere in your codebase, even if the options seem to be identical. If you wish to force a match, you may provide your own key in `options`.
+::
+
+::note
+If you use `useFetch` to call an (external) HTTPS URL with a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.
+::
+
+:video-accordion{title="Watch a video from Alexander Lichter about client-side caching with getCachedData" videoId="aQPR0xn-MMk"}
+
+## Return Values
+
+- `data`: the result of the asynchronous function that is passed in.
+- `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function.
+- `error`: an error object if the data fetching failed.
+- `status`: a string indicating the status of the data request:
+  - `idle`: when the request has not started, such as:
+    - when `execute` has not yet been called and `{ immediate: false }` is set
+    - when rendering HTML on the server and `{ server: false }` is set
+  - `pending`: the request is in progress
+  - `success`: the request has completed successfully
+  - `error`: the request has failed
+- `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled.
+
+By default, Nuxt waits until a `refresh` is finished before it can be executed again.
+
+::note
+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>`.
+::
+
+## Type
+
+```ts [Signature]
+function useFetch<DataT, ErrorT>(
+  url: string | Request | Ref<string | Request> | (() => string | Request),
+  options?: UseFetchOptions<DataT>
+): Promise<AsyncData<DataT, ErrorT>>
+
+type UseFetchOptions<DataT> = {
+  key?: string
+  method?: string
+  query?: SearchParams
+  params?: SearchParams
+  body?: RequestInit['body'] | Record<string, any>
+  headers?: Record<string, string> | [key: string, value: string][] | Headers
+  baseURL?: string
+  server?: boolean
+  lazy?: boolean
+  immediate?: boolean
+  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
+  deep?: boolean
+  dedupe?: 'cancel' | 'defer'
+  default?: () => DataT
+  transform?: (input: DataT) => DataT | Promise<DataT>
+  pick?: string[]
+  watch?: WatchSource[] | false
+}
+
+type AsyncDataRequestContext = {
+  /** The reason for this data request */
+  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
+}
+
+type AsyncData<DataT, ErrorT> = {
+  data: Ref<DataT | null>
+  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
+  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
+  clear: () => void
+  error: Ref<ErrorT | null>
+  status: Ref<AsyncDataRequestStatus>
+}
+
+interface AsyncDataExecuteOptions {
+  dedupe?: 'cancel' | 'defer'
+}
+
+type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
+```

package/3.api/2.composables/use-head-safe.md

@@ -0,0 +1,55 @@
+---
+title: useHeadSafe
+description: The recommended way to provide head data with user input.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/unjs/unhead/blob/main/packages/vue/src/composables.ts
+    size: xs
+---
+
+The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/api/composables/use-head) composable that restricts the input to only allow safe values.
+
+## Usage
+
+You can pass all the same values as [`useHead`](/docs/api/composables/use-head)
+
+```ts
+useHeadSafe({
+  script: [
+    { id: 'xss-script', innerHTML: 'alert("xss")' }
+  ],
+  meta: [
+    { 'http-equiv': 'refresh', content: '0;javascript:alert(1)' }
+  ]
+})
+// Will safely generate
+// <script id="xss-script"></script>
+// <meta content="0;javascript:alert(1)">
+```
+
+::read-more{to="https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe" target="_blank"}
+Read more on the `Unhead` documentation.
+::
+
+## Type
+
+```ts
+useHeadSafe(input: MaybeComputedRef<HeadSafe>): void
+```
+
+The list of allowed values is:
+
+```ts
+const WhitelistAttributes = {
+  htmlAttrs: ['class', 'style', 'lang', 'dir'],
+  bodyAttrs: ['class', 'style'],
+  meta: ['name', 'property', 'charset', 'content', 'media'],
+  noscript: ['textContent'],
+  style: ['media', 'textContent', 'nonce', 'title', 'blocking'],
+  script: ['type', 'textContent', 'nonce', 'blocking'],
+  link: ['color', 'crossorigin', 'fetchpriority', 'href', 'hreflang', 'imagesrcset', 'imagesizes', 'integrity', 'media', 'referrerpolicy', 'rel', 'sizes', 'type'],
+}
+```
+
+See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/safeSchema.ts) for more detailed types.

package/3.api/2.composables/use-head.md

@@ -0,0 +1,69 @@
+---
+title: useHead
+description: useHead customizes the head properties of individual pages of your Nuxt app.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/unjs/unhead/blob/main/packages/vue/src/composables.ts
+    size: xs
+---
+
+The [`useHead`](/docs/api/composables/use-head) composable function allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.unjs.io). If the data comes from a user or other untrusted source, we recommend you check out [`useHeadSafe`](/docs/api/composables/use-head-safe).
+
+:read-more{to="/docs/getting-started/seo-meta"}
+
+## Type
+
+```ts
+useHead(meta: MaybeComputedRef<MetaObject>): void
+```
+
+Below are the non-reactive types for [`useHead`](/docs/api/composables/use-head) .
+
+```ts
+interface MetaObject {
+  title?: string
+  titleTemplate?: string | ((title?: string) => string)
+  base?: Base
+  link?: Link[]
+  meta?: Meta[]
+  style?: Style[]
+  script?: Script[]
+  noscript?: Noscript[]
+  htmlAttrs?: HtmlAttributes
+  bodyAttrs?: BodyAttributes
+}
+```
+
+See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.
+
+::note
+The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. `meta` parameter can also accept a function returning an object to make the entire object reactive.
+::
+
+## Params
+
+### `meta`
+
+**Type**: `MetaObject`
+
+An object accepting the following head metadata:
+
+- `meta`: Each element in the array is mapped to a newly-created `<meta>` tag, where object properties are mapped to the corresponding attributes.
+  - **Type**: `Array<Record<string, any>>`
+- `link`: Each element in the array is mapped to a newly-created `<link>` tag, where object properties are mapped to the corresponding attributes.
+  - **Type**: `Array<Record<string, any>>`
+- `style`: Each element in the array is mapped to a newly-created `<style>` tag, where object properties are mapped to the corresponding attributes.
+  - **Type**: `Array<Record<string, any>>`
+- `script`: Each element in the array is mapped to a newly-created `<script>` tag, where object properties are mapped to the corresponding attributes.
+  - **Type**: `Array<Record<string, any>>`
+- `noscript`: Each element in the array is mapped to a newly-created `<noscript>` tag, where object properties are mapped to the corresponding attributes.
+  - **Type**: `Array<Record<string, any>>`
+- `titleTemplate`: Configures dynamic template to customize the page title on an individual page.
+  - **Type**: `string` | `((title: string) => string)`
+- `title`: Sets static page title on an individual page.
+  - **Type**: `string`
+- `bodyAttrs`: Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute.
+  - **Type**: `Record<string, any>`
+- `htmlAttrs`: Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute.
+  - **Type**: `Record<string, any>`

package/3.api/2.composables/use-hydration.md

@@ -0,0 +1,68 @@
+---
+title: 'useHydration'
+description: 'Allows full control of the hydration cycle to set and receive data from the server.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/hydrate.ts
+    size: xs
+---
+
+::note
+This is an advanced composable, primarily designed for use within plugins, mostly used by Nuxt modules.
+::
+
+::note
+`useHydration` is designed to **ensure state synchronization and restoration during SSR**. If you need to create a globally reactive state that is SSR-friendly in Nuxt, [`useState`](/docs/api/composables/use-state) is the recommended choice.
+::
+
+`useHydration` is a built-in composable that provides a way to set data on the server side every time a new HTTP request is made and receive that data on the client side. This way `useHydration` allows you to take full control of the hydration cycle.
+
+The data returned from the `get` function on the server is stored in `nuxtApp.payload` under the unique key provided as the first parameter to `useHydration`. During hydration, this data is then retrieved on the client, preventing redundant computations or API calls.
+
+## Usage
+
+::code-group
+
+```ts [Without useHydration]
+export default defineNuxtPlugin((nuxtApp) => {
+  const myStore = new MyStore()
+
+  if (import.meta.server) {
+    nuxt.hooks.hook('app:rendered', () => {
+      nuxtApp.payload.myStoreState = myStore.getState()
+    })
+  }
+
+  if (import.meta.client) {
+    nuxt.hooks.hook('app:created', () => {
+      myStore.setState(nuxtApp.payload.myStoreState)
+    })
+  }
+})
+```
+
+```ts [With useHydration]
+export default defineNuxtPlugin((nuxtApp) => {
+  const myStore = new MyStore()
+
+  useHydration(
+    'myStoreState', 
+    () => myStore.getState(), 
+    (data) => myStore.setState(data)
+  )
+})
+```
+::
+
+## Type
+
+```ts [signature]
+useHydration <T> (key: string, get: () => T, set: (value: T) => void) => void
+```
+
+## Parameters
+
+- `key`: A unique key that identifies the data in your Nuxt application.
+- `get`: A function executed **only on the server** (called when SSR rendering is done) to set the initial value.
+- `set`: A function executed **only on the client** (called when initial vue instance is created) to receive the data.

package/3.api/2.composables/use-lazy-async-data.md

@@ -0,0 +1,47 @@
+---
+title: useLazyAsyncData
+description: This wrapper around useAsyncData triggers navigation immediately.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/asyncData.ts
+    size: xs
+---
+
+## Description
+
+By default, [`useAsyncData`](/docs/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
+
+::note
+`useLazyAsyncData` has the same signature as [`useAsyncData`](/docs/api/composables/use-async-data).
+::
+
+:read-more{to="/docs/api/composables/use-async-data"}
+
+## Example
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+/* Navigation will occur before fetching is complete.
+  Handle 'pending' and 'error' states directly within your component's template
+*/
+const { status, data: count } = await useLazyAsyncData('count', () => $fetch('/api/count'))
+
+watch(count, (newCount) => {
+  // Because count might start out null, you won't have access
+  // to its contents immediately, but you can watch it.
+})
+</script>
+
+<template>
+  <div>
+    {{ status === 'pending' ? 'Loading' : count }}
+  </div>
+</template>
+```
+
+::warning
+`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.
+::
+
+:read-more{to="/docs/getting-started/data-fetching"}

package/3.api/2.composables/use-lazy-fetch.md

@@ -0,0 +1,55 @@
+---
+title: 'useLazyFetch'
+description: This wrapper around useFetch triggers navigation immediately.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/fetch.ts
+    size: xs
+---
+
+## Description
+
+By default, [`useFetch`](/docs/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` provides a wrapper around [`useFetch`](/docs/api/composables/use-fetch) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.
+
+::note
+`useLazyFetch` has the same signature as [`useFetch`](/docs/api/composables/use-fetch).
+::
+
+::note
+Awaiting `useLazyFetch` in this mode only ensures the call is initialized. On client-side navigation, data may not be immediately available, and you should make sure to handle the pending state in your app.
+::
+
+:read-more{to="/docs/api/composables/use-fetch"}
+
+## Example
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+/* Navigation will occur before fetching is complete.
+ * Handle 'pending' and 'error' states directly within your component's template
+ */
+const { status, data: posts } = await useLazyFetch('/api/posts')
+watch(posts, (newPosts) => {
+  // Because posts might start out null, you won't have access
+  // to its contents immediately, but you can watch it.
+})
+</script>
+
+<template>
+  <div v-if="status === 'pending'">
+    Loading ...
+  </div>
+  <div v-else>
+    <div v-for="post in posts">
+      <!-- do something -->
+    </div>
+  </div>
+</template>
+```
+
+::note
+`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.
+::
+
+:read-more{to="/docs/getting-started/data-fetching"}

package/3.api/2.composables/use-loading-indicator.md

@@ -0,0 +1,77 @@
+---
+title: 'useLoadingIndicator'
+description: This composable gives you access to the loading state of the app page.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/loading-indicator.ts
+    size: xs
+---
+
+## Description
+
+A composable which returns the loading state of the page. Used by [`<NuxtLoadingIndicator>`](/docs/api/components/nuxt-loading-indicator) and controllable.
+It hooks into [`page:loading:start`](/docs/api/advanced/hooks#app-hooks-runtime) and [`page:loading:end`](/docs/api/advanced/hooks#app-hooks-runtime) to change its state.
+
+## Parameters
+
+- `duration`: Duration of the loading bar, in milliseconds (default `2000`).
+- `throttle`: Throttle the appearing and hiding, in milliseconds (default `200`).
+- `estimatedProgress`: By default Nuxt will back off as it approaches 100%. You can provide a custom function to customize the progress estimation, which is a function that receives the duration of the loading bar (above) and the elapsed time. It should return a value between 0 and 100.
+
+## Properties
+
+### `isLoading`
+
+- **type**: `Ref<boolean>`
+- **description**: The loading state
+
+### `error`
+
+- **type**: `Ref<boolean>`
+- **description**: The error state
+
+### `progress`
+
+- **type**: `Ref<number>`
+- **description**: The progress state. From `0` to `100`.
+
+## Methods
+
+### `start()`
+
+Set `isLoading` to true and start to increase the `progress` value. `start` accepts a `{ force: true }` option to skip the interval and show the loading state immediately.
+
+### `set()`
+
+Set the `progress` value to a specific value. `set` accepts a `{ force: true }` option to skip the interval and show the loading state immediately.
+
+### `finish()`
+
+Set the `progress` value to `100`, stop all timers and intervals then reset the loading state `500` ms later. `finish` accepts a `{ force: true }` option to skip the interval before the state is reset, and `{ error: true }` to change the loading bar color and set the error property to true.
+
+### `clear()`
+
+Used by `finish()`. Clear all timers and intervals used by the composable.
+
+## Example
+
+```vue
+<script setup lang="ts">
+  const { progress, isLoading, start, finish, clear } = useLoadingIndicator({
+    duration: 2000,
+    throttle: 200,
+    // This is how progress is calculated by default
+    estimatedProgress: (duration, elapsed) => (2 / Math.PI * 100) * Math.atan(elapsed / duration * 100 / 50)
+  })
+</script>
+```
+
+```vue
+<script setup lang="ts">
+  const { start, set } = useLoadingIndicator()
+  // same as set(0, { force: true })
+  // set the progress to 0, and show loading immediately
+  start({ force: true })
+</script>
+```