@nuxt/docs 0.0.0 → 3.17.0

package/3.api/2.composables/use-request-url.md

@@ -0,0 +1,41 @@
+---
+title: 'useRequestURL'
+description: 'Access the incoming request URL with the useRequestURL composable.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/url.ts
+    size: xs
+---
+
+`useRequestURL` is a helper function that returns an [URL object](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) working on both server-side and client-side.
+
+::important
+When utilizing [Hybrid Rendering](/docs/guide/concepts/rendering#hybrid-rendering) with cache strategies, all incoming request headers are dropped when handling the cached responses via the [Nitro caching layer](https://nitro.unjs.io/guide/cache) (meaning `useRequestURL` will return `localhost` for the `host`).
+
+You can define the [`cache.varies` option](https://nitro.unjs.io/guide/cache#options) to specify headers that will be considered when caching and serving the responses, such as `host` and `x-forwarded-host` for multi-tenant environments.
+::
+
+::code-group
+
+```vue [pages/about.vue]
+<script setup lang="ts">
+const url = useRequestURL()
+</script>
+
+<template>
+  <p>URL is: {{ url }}</p>
+  <p>Path is: {{ url.pathname }}</p>
+</template>
+```
+
+```html [Result in development]
+<p>URL is: http://localhost:3000/about</p>
+<p>Path is: /about</p>
+```
+
+::
+
+::tip{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/URL#instance_properties" target="_blank"}
+Read about the URL instance properties on the MDN documentation.
+::

package/3.api/2.composables/use-response-header.md

@@ -0,0 +1,48 @@
+---
+title: "useResponseHeader"
+description: "Use useResponseHeader to set a server response header."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ssr.ts
+    size: xs
+---
+
+::important
+This composable is available in Nuxt v3.14+.
+::
+
+You can use the built-in [`useResponseHeader`](/docs/api/composables/use-response-header) composable to set any server response header within your pages, components, and plugins.
+
+```ts
+// Set the a custom response header
+const header = useResponseHeader('X-My-Header');
+header.value = 'my-value';
+```
+
+## Example
+
+We can use `useResponseHeader` to easily set a response header on a per-page basis.
+
+```vue [pages/test.vue]
+<script setup>
+// pages/test.vue
+const header = useResponseHeader('X-My-Header');
+header.value = 'my-value';
+</script>
+
+<template>
+  <h1>Test page with custom header</h1>
+  <p>The response from the server for this "/test" page will have a custom "X-My-Header" header.</p>
+</template>
+```
+
+We can use `useResponseHeader` for example in Nuxt [middleware](/docs/guide/directory-structure/middleware) to set a response header for all pages.
+
+```ts [middleware/my-header-middleware.ts]
+export default defineNuxtRouteMiddleware((to, from) => {
+  const header = useResponseHeader('X-My-Always-Header');
+  header.value = `I'm Always here!`;
+});
+
+```

package/3.api/2.composables/use-route-announcer.md

@@ -0,0 +1,60 @@
+---
+title: 'useRouteAnnouncer'
+description: This composable observes the page title changes and updates the announcer message accordingly.
+navigation:
+  badge: New
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/route-announcer.ts
+    size: xs
+---
+
+::important
+This composable is available in Nuxt v3.12+.
+::
+
+## Description
+
+A composable which observes the page title changes and updates the announcer message accordingly. Used by [`<NuxtRouteAnnouncer>`](/docs/api/components/nuxt-route-announcer) and controllable.
+It hooks into Unhead's [`dom:rendered`](https://unhead.unjs.io/docs/typescript/head/api/hooks/dom-rendered) to read the page's title and set it as the announcer message.
+
+## Parameters
+
+- `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately).  (default `polite`).
+
+## Properties
+
+### `message`
+
+- **type**: `Ref<string>`
+- **description**: The message to announce
+
+### `politeness`
+
+- **type**: `Ref<string>`
+- **description**: Screen reader announcement urgency level `off`, `polite`, or `assertive`
+
+## Methods
+
+### `set(message, politeness = "polite")`
+
+Sets the message to announce with its urgency level.
+
+### `polite(message)`
+
+Sets the message with `politeness = "polite"`
+
+### `assertive(message)`
+
+Sets the message with `politeness = "assertive"`
+
+## Example
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+  const { message, politeness, set, polite, assertive } = useRouteAnnouncer({
+    politeness: 'assertive'
+  })
+</script>
+```

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

@@ -0,0 +1,52 @@
+---
+title: "useRoute"
+description: The useRoute composable returns the current route.
+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
+Within the template of a Vue component, you can access the route using `$route`.
+::
+
+## Example
+
+In the following example, we call an API via [`useFetch`](/docs/api/composables/use-fetch) using a dynamic page parameter - `slug` - as part of the URL.
+
+```html [~/pages/[slug\\].vue]
+<script setup lang="ts">
+const route = useRoute()
+const { data: mountain } = await useFetch(`/api/mountains/${route.params.slug}`)
+</script>
+
+<template>
+  <div>
+    <h1>{{ mountain.title }}</h1>
+    <p>{{ mountain.description }}</p>
+  </div>
+</template>
+```
+
+If you need to access the route query parameters (for example `example` in the path `/test?example=true`), then you can use `useRoute().query` instead of `useRoute().params`.
+
+## API
+
+Apart from dynamic parameters and query parameters, `useRoute()` also provides the following computed references related to the current route:
+
+- `fullPath`: encoded URL associated with the current route that contains path, query and hash
+- `hash`: decoded hash section of the URL that starts with a #
+- `query`: access route query parameters
+- `matched`: array of normalized matched routes with current route location
+- `meta`: custom data attached to the record
+- `name`: unique name for the route record
+- `path`: encoded pathname section of the URL
+- `redirectedFrom`: route location that was attempted to access before ending up on the current route location
+
+::note
+Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` in your template can trigger hydration issues because this will include the fragment on client but not the server.
+::
+
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/#RouteLocationNormalizedLoaded"}

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

@@ -0,0 +1,92 @@
+---
+title: "useRouter"
+description: "The useRouter composable returns the router instance."
+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
+---
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+const router = useRouter()
+</script>
+```
+
+If you only need the router instance within your template, use `$router`:
+
+```vue [pages/index.vue]
+<template>
+  <button @click="$router.back()">Back</button>
+</template>
+```
+
+If you have a `pages/` directory, `useRouter` is identical in behavior to the one provided by `vue-router`.
+
+::read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/interfaces/Router.html#Properties-currentRoute" target="_blank"}
+Read `vue-router` documentation about the `Router` interface.
+::
+
+## Basic Manipulation
+
+- [`addRoute()`](https://router.vuejs.org/api/interfaces/Router.html#addRoute): Add a new route to the router instance. `parentName` can be provided to add new route as the child of an existing route.
+- [`removeRoute()`](https://router.vuejs.org/api/interfaces/Router.html#removeRoute): Remove an existing route by its name.
+- [`getRoutes()`](https://router.vuejs.org/api/interfaces/Router.html#getRoutes): Get a full list of all the route records.
+- [`hasRoute()`](https://router.vuejs.org/api/interfaces/Router.html#hasRoute): Checks if a route with a given name exists.
+- [`resolve()`](https://router.vuejs.org/api/interfaces/Router.html#resolve): Returns the normalized version of a route location. Also includes an `href` property that includes any existing base.
+
+```ts [Example]
+const router = useRouter()
+
+router.addRoute({ name: 'home', path: '/home', component: Home })
+router.removeRoute('home')
+router.getRoutes()
+router.hasRoute('home')
+router.resolve({ name: 'home' })
+```
+
+::note
+`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/guide/directory-structure/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.
+::
+
+## Based on History API
+
+- [`back()`](https://router.vuejs.org/api/interfaces/Router.html#back): Go back in history if possible, same as `router.go(-1)`.
+- [`forward()`](https://router.vuejs.org/api/interfaces/Router.html#forward): Go forward in history if possible, same as `router.go(1)`.
+- [`go()`](https://router.vuejs.org/api/interfaces/Router.html#go): Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`.
+- [`push()`](https://router.vuejs.org/api/interfaces/Router.html#push): Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](/docs/api/utils/navigate-to) instead.**
+- [`replace()`](https://router.vuejs.org/api/interfaces/Router.html#replace): Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](/docs/api/utils/navigate-to) instead.**
+
+```ts [Example]
+const router = useRouter()
+
+router.back()
+router.forward()
+router.go(3)
+router.push({ path: "/home" })
+router.replace({ hash: "#bio" })
+```
+
+::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/History" target="_blank"}
+Read more about the browser's History API.
+::
+
+## Navigation Guards
+
+`useRouter` composable provides `afterEach`, `beforeEach` and `beforeResolve` helper methods that acts as navigation guards.
+
+However, Nuxt has a concept of **route middleware** that simplifies the implementation of navigation guards and provides a better developer experience.
+
+:read-more{to="/docs/guide/directory-structure/middleware"}
+
+## Promise and Error Handling
+
+- [`isReady()`](https://router.vuejs.org/api/interfaces/Router.html#isReady): Returns a Promise that resolves when the router has completed the initial navigation.
+- [`onError`](https://router.vuejs.org/api/interfaces/Router.html#onError): Adds an error handler that is called every time a non caught error happens during navigation.
+
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/interfaces/Router.html#Methods" title="Vue Router Docs" target="_blank"}
+
+## Universal Router Instance
+
+If you do not have a `pages/` folder, then [`useRouter`](/docs/api/composables/use-router)  will return a universal router instance with similar helper methods, but be aware that not all features may be supported or behave in exactly the same way as with `vue-router`.

package/3.api/2.composables/use-runtime-config.md

@@ -0,0 +1,142 @@
+---
+title: 'useRuntimeConfig'
+description: 'Access runtime config variables with the useRuntimeConfig composable.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts
+    size: xs
+---
+
+## Usage
+
+```vue [app.vue]
+<script setup lang="ts">
+const config = useRuntimeConfig()
+</script>
+```
+
+```ts [server/api/foo.ts]
+export default defineEventHandler((event) => {
+  const config = useRuntimeConfig(event)
+})
+```
+
+:read-more{to="/docs/guide/going-further/runtime-config"}
+
+## Define Runtime Config
+
+The example below shows how to set a public API base URL and a secret API token that is only accessible on the server.
+
+We should always define `runtimeConfig` variables inside `nuxt.config`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  runtimeConfig: {
+    // Private keys are only available on the server
+    apiSecret: '123',
+
+    // Public keys that are exposed to the client
+    public: {
+      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
+    }
+  }
+})
+```
+
+::note
+Variables that need to be accessible on the server are added directly inside `runtimeConfig`. Variables that need to be accessible on both the client and the server are defined in `runtimeConfig.public`.
+::
+
+:read-more{to="/docs/guide/going-further/runtime-config"}
+
+## Access Runtime Config
+
+To access runtime config, we can use `useRuntimeConfig()` composable:
+
+```ts [server/api/test.ts]
+export default defineEventHandler((event) => {
+  const config = useRuntimeConfig(event)
+
+  // Access public variables
+  const result = await $fetch(`/test`, {
+    baseURL: config.public.apiBase,
+    headers: {
+      // Access a private variable (only available on the server)
+      Authorization: `Bearer ${config.apiSecret}`
+    }
+  })
+  return result
+}
+```
+
+In this example, since `apiBase` is defined within the `public` namespace, it is universally accessible on both server and client-side, while `apiSecret` **is only accessible on the server-side**.
+
+## Environment Variables
+
+It is possible to update runtime config values using a matching environment variable name prefixed with `NUXT_`.
+
+:read-more{to="/docs/guide/going-further/runtime-config"}
+
+### Using the `.env` File
+
+We can set the environment variables inside the `.env` file to make them accessible during **development** and **build/generate**.
+
+```ini [.env]
+NUXT_PUBLIC_API_BASE = "https://api.localhost:5555"
+NUXT_API_SECRET = "123"
+```
+
+::note
+Any environment variables set within `.env` file are accessed using `process.env` in the Nuxt app during **development** and **build/generate**.
+::
+
+::warning
+In **production runtime**, you should use platform environment variables and `.env` is not used.
+::
+
+:read-more{to="/docs/guide/directory-structure/env"}
+
+## `app` namespace
+
+Nuxt uses `app` namespace in runtime-config with keys including `baseURL` and `cdnURL`. You can customize their values at runtime by setting environment variables.
+
+::note
+This is a reserved namespace. You should not introduce additional keys inside `app`.
+::
+
+### `app.baseURL`
+
+By default, the `baseURL` is set to `'/'`.
+
+However, the `baseURL` can be updated at runtime by setting the `NUXT_APP_BASE_URL` as an environment variable.
+
+Then, you can access this new base URL using `config.app.baseURL`:
+
+```ts [/plugins/my-plugin.ts]
+export default defineNuxtPlugin((NuxtApp) => {
+  const config = useRuntimeConfig()
+
+  // Access baseURL universally
+  const baseURL = config.app.baseURL
+})
+```
+
+### `app.cdnURL`
+
+This example shows how to set a custom CDN url and access them using `useRuntimeConfig()`.
+
+You can use a custom CDN for serving static assets inside `.output/public` using the `NUXT_APP_CDN_URL` environment variable.
+
+And then access the new CDN url using `config.app.cdnURL`.
+
+```ts [server/api/foo.ts]
+export default defineEventHandler((event) => {
+  const config = useRuntimeConfig(event)
+
+  // Access cdnURL universally
+  const cdnURL = config.app.cdnURL
+})
+```
+
+:read-more{to="/docs/guide/going-further/runtime-config"}

package/3.api/2.composables/use-runtime-hook.md

@@ -0,0 +1,43 @@
+---
+title: useRuntimeHook
+description: Registers a runtime hook in a Nuxt application and ensures it is properly disposed of when the scope is destroyed.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/runtime-hook.ts
+    size: xs
+---
+
+::important
+This composable is available in Nuxt v3.14+.
+::
+
+```ts [signature]
+function useRuntimeHook<THookName extends keyof RuntimeNuxtHooks>(
+  name: THookName,
+  fn: RuntimeNuxtHooks[THookName] extends HookCallback ? RuntimeNuxtHooks[THookName] : never
+): void
+```
+
+## Usage
+
+### Parameters
+
+- `name`: The name of the runtime hook to register. You can see the full list of [runtime Nuxt hooks here](/docs/api/advanced/hooks#app-hooks-runtime).
+- `fn`: The callback function to execute when the hook is triggered. The function signature varies based on the hook name.
+
+### Returns
+
+The composable doesn't return a value, but it automatically unregisters the hook when the component's scope is destroyed.
+
+## Example
+
+```vue twoslash [pages/index.vue]
+<script setup lang="ts">
+// Register a hook that runs every time a link is prefetched, but which will be
+// automatically cleaned up (and not called again) when the component is unmounted
+useRuntimeHook('link:prefetch', (link) => {
+  console.log('Prefetching', link)
+})
+</script>
+```

package/3.api/2.composables/use-seo-meta.md

@@ -0,0 +1,80 @@
+---
+title: 'useSeoMeta'
+description: The useSeoMeta composable lets you define your site's SEO meta tags as a flat object with full TypeScript support.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/unjs/unhead/blob/main/packages/vue/src/composables.ts
+    size: xs
+---
+
+This helps you avoid common mistakes, such as using `name` instead of `property`, as well as typos - with over 100+ meta tags fully typed.
+
+::important
+This is the recommended way to add meta tags to your site as it is XSS safe and has full TypeScript support.
+::
+
+:read-more{to="/docs/getting-started/seo-meta"}
+
+## Usage
+
+```vue [app.vue]
+<script setup lang="ts">
+useSeoMeta({
+  title: 'My Amazing Site',
+  ogTitle: 'My Amazing Site',
+  description: 'This is my amazing site, let me tell you all about it.',
+  ogDescription: 'This is my amazing site, let me tell you all about it.',
+  ogImage: 'https://example.com/image.png',
+  twitterCard: 'summary_large_image',
+})
+</script>
+```
+
+When inserting tags that are reactive, you should use the computed getter syntax (`() => value`):
+
+```vue [app.vue]
+<script setup lang="ts">
+const title = ref('My title')
+
+useSeoMeta({
+  title,
+  description: () => `This is a description for the ${title.value} page`
+})
+</script>
+```
+
+## Parameters
+
+There are over 100 parameters. See the [full list of parameters in the source code](https://github.com/harlan-zw/zhead/blob/main/packages/zhead/src/metaFlat.ts#L1035).
+
+:read-more{to="/docs/getting-started/seo-meta"}
+
+## Performance
+
+In most instances, SEO meta tags don't need to be reactive as search engine robots primarily scan the initial page load.
+
+For better performance, you can wrap your `useSeoMeta` calls in a server-only condition when the meta tags don't need to be reactive:
+
+```vue [app.vue]
+<script setup lang="ts">
+if (import.meta.server) {
+  // These meta tags will only be added during server-side rendering
+  useSeoMeta({
+    robots: 'index, follow',
+    description: 'Static description that does not need reactivity',
+    ogImage: 'https://example.com/image.png',
+    // other static meta tags...
+  })
+}
+
+const dynamicTitle = ref('My title')
+// Only use reactive meta tags outside the condition when necessary
+useSeoMeta({
+  title: () => dynamicTitle.value,
+  ogTitle: () => dynamicTitle.value,
+})
+</script>
+```
+
+This previously used the [`useServerSeoMeta`](/docs/api/composables/use-server-seo-meta) composable, but it has been deprecated in favor of this approach.

package/3.api/2.composables/use-server-seo-meta.md

@@ -0,0 +1,27 @@
+---
+title: 'useServerSeoMeta'
+description: The useServerSeoMeta composable lets you define your site's SEO meta tags as a flat object with full TypeScript support.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/unjs/unhead/blob/main/packages/vue/src/composables.ts
+    size: xs
+---
+
+Just like [`useSeoMeta`](/docs/api/composables/use-seo-meta), `useServerSeoMeta` composable lets you define your site's SEO meta tags as a flat object with full TypeScript support.
+
+:read-more{to="/docs/api/composables/use-seo-meta"}
+
+In most instances, the meta doesn't need to be reactive as robots will only scan the initial load. So we recommend using [`useServerSeoMeta`](/docs/api/composables/use-server-seo-meta) as a performance-focused utility that will not do anything (or return a `head` object) on the client.
+
+```vue [app.vue]
+<script setup lang="ts">
+useServerSeoMeta({
+  robots: 'index, follow'
+})
+</script>
+```
+
+Parameters are exactly the same as with [`useSeoMeta`](/docs/api/composables/use-seo-meta)
+
+:read-more{to="/docs/getting-started/seo-meta"}

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

@@ -0,0 +1,48 @@
+---
+title: "useState"
+description: The useState composable creates a reactive and SSR-friendly shared state.
+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
+---
+
+## Usage
+
+```ts
+// Create a reactive state and set default value
+const count = useState('counter', () => Math.round(Math.random() * 100))
+```
+
+:read-more{to="/docs/getting-started/state-management"}
+
+::important
+Because the data inside `useState` will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.
+::
+
+::warning
+`useState` is a reserved function name transformed by the compiler, so you should not name your own function `useState`.
+::
+
+:video-accordion{title="Watch a video from Alexander Lichter about why and when to use useState" videoId="mv0WcBABcIk"}
+
+## Using `shallowRef`
+
+If you don't need your state to be deeply reactive, you can combine `useState` with [`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref). This can improve performance when your state contains large objects and arrays.
+
+```ts
+const state = useState('my-shallow-state', () => shallowRef({ deep: 'not reactive' }))
+// isShallow(state) === true
+```
+
+## Type
+
+```ts
+useState<T>(init?: () => T | Ref<T>): Ref<T>
+useState<T>(key: string, init?: () => T | Ref<T>): Ref<T>
+```
+
+- `key`: A unique key ensuring that data fetching is properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file and line number of the instance of [`useState`](/docs/api/composables/use-state) will be generated for you.
+- `init`: A function that provides initial value for the state when not initiated. This function can also return a `Ref`.
+- `T`: (typescript only) Specify the type of state