@nuxt/docs 0.0.0 → 3.17.0

package/3.api/3.utils/$fetch.md

@@ -0,0 +1,98 @@
+---
+title: "$fetch"
+description: Nuxt uses ofetch to expose globally the $fetch helper for making HTTP requests.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/entry.ts
+    size: xs
+---
+
+Nuxt uses [ofetch](https://github.com/unjs/ofetch) to expose globally the `$fetch` helper for making HTTP requests within your Vue app or API routes.
+
+::tip{icon="i-lucide-rocket"}
+During server-side rendering, calling `$fetch` to fetch your internal [API routes](/docs/guide/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.
+::
+
+::note{color="blue" icon="i-lucide-info"}
+Using `$fetch` in components without wrapping it with [`useAsyncData`](/docs/api/composables/use-async-data) causes fetching the data twice: initially on the server, then again on the client-side during hydration, because `$fetch` does not transfer state from the server to the client. Thus, the fetch will be executed on both sides because the client has to get the data again.
+::
+
+## Usage
+
+We recommend to use [`useFetch`](/docs/api/composables/use-fetch) or [`useAsyncData`](/docs/api/composables/use-async-data) + `$fetch` to prevent double data fetching when fetching the component data.
+
+```vue [app.vue]
+<script setup lang="ts">
+// During SSR data is fetched twice, once on the server and once on the client.
+const dataTwice = await $fetch('/api/item')
+
+// During SSR data is fetched only on the server side and transferred to the client.
+const { data } = await useAsyncData('item', () => $fetch('/api/item'))
+
+// You can also useFetch as shortcut of useAsyncData + $fetch
+const { data } = await useFetch('/api/item')
+</script>
+```
+
+:read-more{to="/docs/getting-started/data-fetching"}
+
+You can use `$fetch` in any methods that are executed only on client-side.
+
+```vue [pages/contact.vue]
+<script setup lang="ts">
+async function contactForm() {
+  await $fetch('/api/contact', {
+    method: 'POST',
+    body: { hello: 'world '}
+  })
+}
+</script>
+
+<template>
+  <button @click="contactForm">Contact</button>
+</template>
+```
+
+::tip
+`$fetch` is the preferred way to make HTTP calls in Nuxt instead of [@nuxt/http](https://github.com/nuxt/http) and [@nuxtjs/axios](https://github.com/nuxt-community/axios-module) that are made for Nuxt 2.
+::
+
+::note
+If you use `$fetch` 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.
+::
+
+### Passing Headers and Cookies
+
+When we call `$fetch` in the browser, user headers like `cookie` will be directly sent to the API.
+
+However, during Server-Side Rendering, due to security risks such as **Server-Side Request Forgery (SSRF)** or **Authentication Misuse**, the `$fetch` wouldn't include the user's browser cookies, nor pass on cookies from the fetch response.
+
+::code-group
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+// This will NOT forward headers or cookies during SSR
+const { data } = await useAsyncData(() => $fetch('/api/cookies'))
+</script>
+```
+
+```ts [server/api/cookies.ts]
+export default defineEventHandler((event) => {
+  const foo = getCookie(event, 'foo')
+  // ... Do something with the cookie
+})
+```
+::
+
+If you need to forward headers and cookies on the server, you must manually pass them:
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+// This will forward the user's headers and cookies to `/api/cookies`
+const requestFetch = useRequestFetch()
+const { data } = await useAsyncData(() => requestFetch('/api/cookies'))
+</script>
+```
+
+However, when calling `useFetch` with a relative URL on the server, Nuxt will use [`useRequestFetch`](/docs/api/composables/use-request-fetch) to proxy headers and cookies (with the exception of headers not meant to be forwarded, like `host`).

package/3.api/3.utils/.navigation.yml

@@ -0,0 +1,3 @@
+title: 'Utils'
+titleTemplate: '%s · Nuxt Utils'
+navigation.icon: i-lucide-square-function

package/3.api/3.utils/abort-navigation.md

@@ -0,0 +1,73 @@
+---
+title: 'abortNavigation'
+description: 'abortNavigation is a helper function that prevents navigation from taking place and throws an error if one is set as a parameter.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/router.ts
+    size: xs
+---
+
+::warning
+`abortNavigation` is only usable inside a [route middleware handler](/docs/guide/directory-structure/middleware).
+::
+
+## Type
+
+```ts
+abortNavigation(err?: Error | string): false
+```
+
+## Parameters
+
+### `err`
+
+- **Type**: [`Error`](https://developer.mozilla.org/pl/docs/Web/JavaScript/Reference/Global_Objects/Error) | `string`
+
+  Optional error to be thrown by `abortNavigation`.
+
+## Examples
+
+The example below shows how you can use `abortNavigation` in a route middleware to prevent unauthorized route access:
+
+```ts [middleware/auth.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useState('user')
+
+  if (!user.value.isAuthorized) {
+    return abortNavigation()
+  }
+
+  if (to.path !== '/edit-post') {
+    return navigateTo('/edit-post')
+  }
+})
+```
+
+### `err` as a String
+
+You can pass the error as a string:
+
+```ts [middleware/auth.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  const user = useState('user')
+
+  if (!user.value.isAuthorized) {
+    return abortNavigation('Insufficient permissions.')
+  }
+})
+```
+
+### `err` as an Error Object
+
+You can pass the error as an [`Error`](https://developer.mozilla.org/pl/docs/Web/JavaScript/Reference/Global_Objects/Error) object, e.g. caught by the `catch`-block:
+
+```ts [middleware/auth.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  try {
+    /* code that might throw an error */
+  } catch (err) {
+    return abortNavigation(err)
+  }
+})
+```

package/3.api/3.utils/add-route-middleware.md

@@ -0,0 +1,88 @@
+---
+title: 'addRouteMiddleware'
+description: 'addRouteMiddleware() is a helper function to dynamically add middleware in your application.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/router.ts
+    size: xs
+---
+
+::note
+Route middleware are navigation guards stored in the [`middleware/`](/docs/guide/directory-structure/middleware) directory of your Nuxt application (unless [set otherwise](/docs/api/nuxt-config#middleware)).
+::
+
+## Type
+
+```ts
+function addRouteMiddleware (name: string, middleware: RouteMiddleware, options?: AddRouteMiddlewareOptions): void
+function addRouteMiddleware (middleware: RouteMiddleware): void
+
+interface AddRouteMiddlewareOptions {
+  global?: boolean
+}
+```
+
+## Parameters
+
+### `name`
+
+- **Type:** `string` | `RouteMiddleware`
+
+Can be either a string or a function of type `RouteMiddleware`. Function takes the next route `to` as the first argument and the current route `from` as the second argument, both of which are Vue route objects.
+
+Learn more about available properties of [route objects](/docs/api/composables/use-route).
+
+### `middleware`
+
+- **Type:** `RouteMiddleware`
+
+The second argument is a function of type `RouteMiddleware`. Same as above, it provides `to` and `from` route objects. It becomes optional if the first argument in `addRouteMiddleware()` is already passed as a function.
+
+### `options`
+
+- **Type:** `AddRouteMiddlewareOptions`
+
+An optional `options` argument lets you set the value of `global` to `true` to indicate whether the router middleware is global or not (set to `false` by default).
+
+## Examples
+
+### Named Route Middleware
+
+Named route middleware is defined by providing a string as the first argument and a function as the second:
+
+```ts [plugins/my-plugin.ts]
+export default defineNuxtPlugin(() => {
+  addRouteMiddleware('named-middleware', () => {
+    console.log('named middleware added in Nuxt plugin')
+  })
+})
+```
+
+When defined in a plugin, it overrides any existing middleware of the same name located in the `middleware/` directory.
+
+### Global Route Middleware
+
+Global route middleware can be defined in two ways:
+
+- Pass a function directly as the first argument without a name. It will automatically be treated as global middleware and applied on every route change.
+
+  ```ts [plugins/my-plugin.ts]
+  export default defineNuxtPlugin(() => {
+    addRouteMiddleware((to, from) => {
+      console.log('anonymous global middleware that runs on every route change')
+    })
+  })
+  ```
+
+- Set an optional, third argument `{ global: true }` to indicate whether the route middleware is global.
+
+  ```ts [plugins/my-plugin.ts]
+  export default defineNuxtPlugin(() => {
+    addRouteMiddleware('global-middleware', (to, from) => {
+        console.log('global middleware that runs on every route change')
+      },
+      { global: true }
+    )
+  })
+  ```

package/3.api/3.utils/call-once.md

@@ -0,0 +1,92 @@
+---
+title: "callOnce"
+description: "Run a given function or block of code once during SSR or CSR."
+navigation:
+  badge: New
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/once.ts
+    size: xs
+---
+
+::important
+This utility is available since [Nuxt v3.9](/blog/v3-9).
+::
+
+## 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
+
+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')
+
+await callOnce(async () => {
+  console.log('This will only be logged once')
+  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
+})
+</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.
+::
+
+:read-more{to="/docs/getting-started/state-management"}
+
+::warning
+Note that `callOnce` doesn't return anything. You should use [`useAsyncData`](/docs/api/composables/use-async-data) or [`useFetch`](/docs/api/composables/use-fetch) 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
+
+```ts
+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. It can be asynchronous.
+- `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

package/3.api/3.utils/clear-error.md

@@ -0,0 +1,29 @@
+---
+title: "clearError"
+description: "The clearError composable clears all handled errors."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/error.ts
+    size: xs
+---
+
+Within your pages, components, and plugins, you can use `clearError` to clear all errors and redirect the user.
+
+**Parameters:**
+
+- `options?: { redirect?: string }`
+
+You can provide an optional path to redirect to (for example, if you want to navigate to a 'safe' page).
+
+```js
+// Without redirect
+clearError()
+
+// With redirect
+clearError({ redirect: '/homepage' })
+```
+
+Errors are set in state using [`useError()`](/docs/api/composables/use-error). The `clearError` composable will reset this state and calls the `app:error:cleared` hook with the provided options.
+
+:read-more{to="/docs/getting-started/error-handling"}

package/3.api/3.utils/clear-nuxt-data.md

@@ -0,0 +1,23 @@
+---
+title: 'clearNuxtData'
+description: Delete cached data, error status and pending promises of useAsyncData and useFetch.
+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
+---
+
+::note
+This method is useful if you want to invalidate the data fetching for another page.
+::
+
+## Type
+
+```ts
+clearNuxtData (keys?: string | string[] | ((key: string) => boolean)): void
+```
+
+## Parameters
+
+* `keys`: One or an array of keys that are used in [`useAsyncData`](/docs/api/composables/use-async-data) to delete their cached data. If no keys are provided, **all data** will be invalidated.

package/3.api/3.utils/clear-nuxt-state.md

@@ -0,0 +1,23 @@
+---
+title: 'clearNuxtState'
+description: Delete the cached state of useState.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/state.ts
+    size: xs
+---
+
+::note
+This method is useful if you want to invalidate the state of `useState`.
+::
+
+## Type
+
+```ts
+clearNuxtState (keys?: string | string[] | ((key: string) => boolean)): void
+```
+
+## Parameters
+
+- `keys`: One or an array of keys that are used in [`useState`](/docs/api/composables/use-state) to delete their cached state. If no keys are provided, **all state** will be invalidated.

package/3.api/3.utils/create-error.md

@@ -0,0 +1,55 @@
+---
+title: 'createError'
+description: Create an error object with additional metadata.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/error.ts
+    size: xs
+---
+
+You can use this function to create an error object with additional metadata. It is usable in both the Vue and Nitro portions of your app, and is meant to be thrown.
+
+## Parameters
+
+- `err`: `string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }`
+
+You can pass either a string or an object to the `createError` function. If you pass a string, it will be used as the error `message`, and the `statusCode` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `statusCode`, `message`, and other error properties.
+
+## In Vue App
+
+If you throw an error created with `createError`:
+
+- on server-side, it will trigger a full-screen error page which you can clear with `clearError`.
+- on client-side, it will throw a non-fatal error for you to handle. If you need to trigger a full-screen error page, then you can do this by setting `fatal: true`.
+
+### Example
+
+```vue [pages/movies/[slug\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const { data } = await useFetch(`/api/movies/${route.params.slug}`)
+if (!data.value) {
+  throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+}
+</script>
+```
+
+## In API Routes
+
+Use `createError` to trigger error handling in server API routes.
+
+### Example
+
+```ts [server/api/error.ts]
+export default eventHandler(() => {
+  throw createError({
+    statusCode: 404,
+    statusMessage: 'Page Not Found'
+  })
+})
+```
+
+In API routes, using `createError` by passing an object with a short `statusMessage` is recommended because it can be accessed on the client side. Otherwise, a `message` passed to `createError` on an API route will not propagate to the client. Alternatively, you can use the `data` property to pass data back to the client. In any case, always consider avoiding to put dynamic user input to the message to avoid potential security issues.
+
+:read-more{to="/docs/getting-started/error-handling"}

package/3.api/3.utils/define-nuxt-component.md

@@ -0,0 +1,53 @@
+---
+title: "defineNuxtComponent"
+description: defineNuxtComponent() is a helper function for defining type safe components with Options API.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/component.ts
+    size: xs
+---
+
+::note
+`defineNuxtComponent()` is a helper function for defining type safe Vue components using options API similar to [`defineComponent()`](https://vuejs.org/api/general.html#definecomponent). `defineNuxtComponent()` wrapper also adds support for `asyncData` and `head` component options.
+::
+
+::note
+Using `<script setup lang="ts">` is the recommended way of declaring Vue components in Nuxt.
+::
+
+:read-more{to=/docs/getting-started/data-fetching}
+
+## `asyncData()`
+
+If you choose not to use `setup()` in your app, you can use the `asyncData()` method within your component definition:
+
+```vue [pages/index.vue]
+<script lang="ts">
+export default defineNuxtComponent({
+  async asyncData() {
+    return {
+      data: {
+        greetings: 'hello world!'
+      }
+    }
+  },
+})
+</script>
+```
+
+## `head()`
+
+If you choose not to use `setup()` in your app, you can use the `head()` method within your component definition:
+
+```vue [pages/index.vue]
+<script lang="ts">
+export default defineNuxtComponent({
+  head(nuxtApp) {
+    return {
+      title: 'My site'
+    }
+  },
+})
+</script>
+```

package/3.api/3.utils/define-nuxt-route-middleware.md

@@ -0,0 +1,67 @@
+---
+title: "defineNuxtRouteMiddleware"
+description: "Create named route middleware using defineNuxtRouteMiddleware helper function."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/router.ts
+    size: xs
+---
+
+Route middleware are stored in the [`middleware/`](/docs/guide/directory-structure/middleware) of your Nuxt application (unless [set otherwise](/docs/api/nuxt-config#middleware)).
+
+## Type
+
+```ts
+defineNuxtRouteMiddleware(middleware: RouteMiddleware) => RouteMiddleware
+
+interface RouteMiddleware {
+  (to: RouteLocationNormalized, from: RouteLocationNormalized): ReturnType<NavigationGuard>
+}
+```
+
+## Parameters
+
+### `middleware`
+
+- **Type**: `RouteMiddleware`
+
+A function that takes two Vue Router's route location objects as parameters: the next route `to` as the first, and the current route `from` as the second.
+
+Learn more about available properties of `RouteLocationNormalized` in the **[Vue Router docs](https://router.vuejs.org/api/#RouteLocationNormalized)**.
+
+## Examples
+
+### Showing Error Page
+
+You can use route middleware to throw errors and show helpful error messages:
+
+```ts [middleware/error.ts]
+export default defineNuxtRouteMiddleware((to) => {
+  if (to.params.id === '1') {
+    throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+  }
+})
+```
+
+The above route middleware will redirect a user to the custom error page defined in the `~/error.vue` file, and expose the error message and code passed from the middleware.
+
+### Redirection
+
+Use [`useState`](/docs/api/composables/use-state) in combination with `navigateTo` helper function inside the route middleware to redirect users to different routes based on their authentication status:
+
+```ts [middleware/auth.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  const auth = useState('auth')
+
+  if (!auth.value.isAuthenticated) {
+    return navigateTo('/login')
+  }
+
+  if (to.path !== '/dashboard') {
+    return navigateTo('/dashboard')
+  }
+})
+```
+
+Both [navigateTo](/docs/api/utils/navigate-to) and [abortNavigation](/docs/api/utils/abort-navigation) are globally available helper functions that you can use inside `defineNuxtRouteMiddleware`.