@nuxt/docs 0.0.0 → 3.17.1

package/3.api/3.utils/define-page-meta.md

@@ -0,0 +1,234 @@
+---
+title: 'definePageMeta'
+description: 'Define metadata for your page components.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/composables.ts
+    size: xs
+---
+
+`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the [`pages/`](/docs/guide/directory-structure/pages) directory (unless [set otherwise](/docs/api/nuxt-config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application.
+
+```vue [pages/some-page.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: 'default'
+})
+</script>
+```
+
+:read-more{to="/docs/guide/directory-structure/pages#page-metadata"}
+
+## Type
+
+```ts
+definePageMeta(meta: PageMeta) => void
+
+interface PageMeta {
+  validate?: (route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>
+  redirect?: RouteRecordRedirectOption
+  name?: string
+  path?: string
+  props?: RouteRecordRaw['props']
+  alias?: string | string[]
+  pageTransition?: boolean | TransitionProps
+  layoutTransition?: boolean | TransitionProps
+  viewTransition?: boolean | 'always'
+  key?: false | string | ((route: RouteLocationNormalizedLoaded) => string)
+  keepalive?: boolean | KeepAliveProps
+  layout?: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>
+  middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
+  scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
+  [key: string]: unknown
+}
+```
+
+## Parameters
+
+### `meta`
+
+- **Type**: `PageMeta`
+
+  An object accepting the following page metadata:
+
+  **`name`**
+
+  - **Type**: `string`
+
+    You may define a name for this page's route. By default, name is generated based on path inside the [`pages/` directory](/docs/guide/directory-structure/pages).
+
+  **`path`**
+
+  - **Type**: `string`
+
+    You may define a [custom regular expression](#using-a-custom-regular-expression) if you have a more complex pattern than can be expressed with the file name.
+
+  **`props`**
+  
+  - **Type**: [`RouteRecordRaw['props']`](https://router.vuejs.org/guide/essentials/passing-props)
+
+    Allows accessing the route `params` as props passed to the page component.
+
+  **`alias`**
+
+  - **Type**: `string | string[]`
+
+    Aliases for the record. Allows defining extra paths that will behave like a copy of the record. Allows having paths shorthands like `/users/:id` and `/u/:id`. All `alias` and `path` values must share the same params.
+
+  **`keepalive`**
+
+  - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive)
+
+    Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive) for a fine-grained control.
+
+  **`key`**
+
+  - **Type**: `false` | `string` | `((route: RouteLocationNormalizedLoaded) => string)`
+
+    Set `key` value when you need more control over when the `<NuxtPage>` component is re-rendered.
+
+  **`layout`**
+
+  - **Type**: `false` | `LayoutKey` | `Ref<LayoutKey>` | `ComputedRef<LayoutKey>`
+
+    Set a static or dynamic name of the layout for each route. This can be set to `false` in case the default layout needs to be disabled.
+
+  **`layoutTransition`**
+
+  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition)
+
+    Set name of the transition to apply for current layout. You can also set this value to `false` to disable the layout transition.
+
+  **`middleware`**
+
+  - **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/NavigationGuard.html#navigationguard) | `Array<MiddlewareKey | NavigationGuard>`
+
+    Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/guide/directory-structure/middleware).
+
+  **`pageTransition`**
+
+  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition)
+
+    Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition.
+
+  **`viewTransition`**
+
+  - **Type**: `boolean | 'always'`
+
+    **Experimental feature, only available when [enabled in your nuxt.config file](/docs/getting-started/transitions#view-transitions-api-experimental)**</br>
+    Enable/disable View Transitions for the current page.
+    If set to true, Nuxt will not apply the transition if the users browser matches `prefers-reduced-motion: reduce` (recommended). If set to `always`, Nuxt will always apply the transition.
+
+  **`redirect`**
+
+  - **Type**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/redirect-and-alias.html#redirect-and-alias)
+
+    Where to redirect if the route is directly matched. The redirection happens before any navigation guard and triggers a new navigation with the new target location.
+
+  **`validate`**
+
+  - **Type**: `(route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>`
+
+    Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with `statusCode`/`statusMessage` to respond immediately with an error (other matches will not be checked).
+
+  **`scrollToTop`**
+
+  - **Type**: `boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean`
+
+    Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in `~/app/router.options.ts` (see [custom routing](/docs/guide/recipes/custom-routing#using-approuteroptions)) for more info.
+
+  **`[key: string]`**
+
+  - **Type**: `any`
+
+    Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/docs/guide/directory-structure/pages/#typing-custom-metadata).
+
+## Examples
+
+### Basic Usage
+
+The example below demonstrates:
+
+- how `key` can be a function that returns a value;
+- how `keepalive` property makes sure that the `<modal>` component is not cached when switching between multiple components;
+- adding `pageType` as a custom property:
+
+```vue [pages/some-page.vue]
+<script setup lang="ts">
+definePageMeta({
+  key: (route) => route.fullPath,
+
+  keepalive: {
+    exclude: ['modal']
+  },
+
+  pageType: 'Checkout'
+})
+</script>
+```
+
+### Defining Middleware
+
+The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `middleware/` directory:
+
+```vue [pages/some-page.vue]
+<script setup lang="ts">
+definePageMeta({
+  // define middleware as a function
+  middleware: [
+    function (to, from) {
+      const auth = useState('auth')
+
+      if (!auth.value.authenticated) {
+          return navigateTo('/login')
+      }
+
+      if (to.path !== '/checkout') {
+        return navigateTo('/checkout')
+      }
+    }
+  ],
+
+  // ... or a string
+  middleware: 'auth'
+
+  // ... or multiple strings
+  middleware: ['auth', 'another-named-middleware']
+})
+</script>
+```
+
+### Using a Custom Regular Expression
+
+A custom regular expression is a good way to resolve conflicts between overlapping routes, for instance:
+
+The two routes "/test-category" and "/1234-post" match both `[postId]-[postSlug].vue` and `[categorySlug].vue` page routes.
+
+To make sure that we are only matching digits (`\d+`) for `postId` in the `[postId]-[postSlug]` route, we can add the following to the `[postId]-[postSlug].vue` page template:
+
+```vue [pages/[postId\\]-[postSlug\\].vue]
+<script setup lang="ts">
+definePageMeta({
+  path: '/:postId(\\d+)-:postSlug' 
+})
+</script>
+```
+
+For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/guide/essentials/route-matching-syntax.html).
+
+### Defining Layout
+
+You can define the layout that matches the layout's file name located (by default) in the [`layouts/` directory](/docs/guide/directory-structure/layouts). You can also disable the layout by setting the `layout` to `false`:
+
+```vue [pages/some-page.vue]
+<script setup lang="ts">
+definePageMeta({
+  // set custom layout
+  layout: 'admin'
+
+  // ... or disable a default layout
+  layout: false
+})
+</script>
+```

package/3.api/3.utils/define-route-rules.md

@@ -0,0 +1,52 @@
+---
+title: 'defineRouteRules'
+description: 'Define route rules for hybrid rendering at the page level.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/composables.ts
+    size: xs
+---
+
+::read-more{to="/docs/guide/going-further/experimental-features#inlinerouterules" icon="i-lucide-star"}
+This feature is experimental and in order to use it you must enable the `experimental.inlineRouteRules` option in your `nuxt.config`.
+::
+
+## Usage
+
+```vue [pages/index.vue]
+<script setup lang="ts">
+defineRouteRules({
+  prerender: true
+})
+</script>
+
+<template>
+  <h1>Hello world!</h1>
+</template>
+```
+
+Will be translated to:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    '/': { prerender: true }
+  }
+})
+```
+
+::note
+When running [`nuxt build`](/docs/api/commands/build), the home page will be pre-rendered in `.output/public/index.html` and statically served.
+::
+
+## Notes
+
+- A rule defined in `~/pages/foo/bar.vue` will be applied to `/foo/bar` requests.
+- A rule in `~/pages/foo/[id].vue` will be applied to `/foo/**` requests.
+
+For more control, such as if you are using a custom `path` or `alias` set in the page's [`definePageMeta`](/docs/api/utils/define-page-meta), you should set `routeRules` directly within your `nuxt.config`.
+
+::read-more{to="/docs/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
+Read more about the `routeRules`.
+::

package/3.api/3.utils/navigate-to.md

@@ -0,0 +1,230 @@
+---
+title: "navigateTo"
+description: navigateTo is a helper function that programmatically navigates users.
+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
+---
+
+## Usage
+
+`navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation.
+
+::warning
+Make sure to always use `await` or `return` on result of `navigateTo` when calling it.
+::
+
+::note
+`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.unjs.io/utils/response#sendredirectevent-location-code) instead.
+::
+
+### Within a Vue Component
+
+```vue
+<script setup lang="ts">
+// passing 'to' as a string
+await navigateTo('/search')
+
+// ... or as a route object
+await navigateTo({ path: '/search' })
+
+// ... or as a route object with query parameters
+await navigateTo({
+  path: '/search',
+  query: {
+    page: 1,
+    sort: 'asc'
+  }
+})
+</script>
+```
+
+### Within Route Middleware
+
+```ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  if (to.path !== '/search') {
+    // setting the redirect code to '301 Moved Permanently'
+    return navigateTo('/search', { redirectCode: 301 })
+  }
+})
+```
+
+When using `navigateTo` within route middleware, you must **return its result** to ensure the middleware execution flow works correctly.
+
+For example, the following implementation **will not work as expected**:
+
+```ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  if (to.path !== '/search') {
+    // ❌ This will not work as expected
+    navigateTo('/search', { redirectCode: 301 })
+    return
+  }
+})
+```
+
+In this case, `navigateTo` will be executed but not returned, which may lead to unexpected behavior.
+
+:read-more{to="/docs/guide/directory-structure/middleware"}
+
+### Navigating to an External URL
+
+The `external` parameter in `navigateTo` influences how navigating to URLs is handled:
+
+- **Without `external: true`**:
+  - Internal URLs navigate as expected.
+  - External URLs throw an error.
+
+- **With `external: true`**:
+  - Internal URLs navigate with a full-page reload.
+  - External URLs navigate as expected.
+
+#### Example
+
+```vue
+<script setup lang="ts">
+// will throw an error;
+// navigating to an external URL is not allowed by default
+await navigateTo('https://nuxt.com')
+
+// will redirect successfully with the 'external' parameter set to 'true'
+await navigateTo('https://nuxt.com', {
+  external: true
+})
+</script>
+```
+
+### Opening a Page in a New Tab
+
+```vue
+<script setup lang="ts">
+// will open 'https://nuxt.com' in a new tab
+await navigateTo('https://nuxt.com', {
+  open: {
+    target: '_blank',
+    windowFeatures: {
+      width: 500,
+      height: 500
+    }
+  }
+})
+</script>
+```
+
+## Type
+
+```ts
+function navigateTo(
+  to: RouteLocationRaw | undefined | null,
+  options?: NavigateToOptions
+) => Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw 
+
+interface NavigateToOptions {
+  replace?: boolean
+  redirectCode?: number
+  external?: boolean
+  open?: OpenOptions
+}
+
+type OpenOptions = {
+  target: string
+  windowFeatures?: OpenWindowFeatures
+}
+
+type OpenWindowFeatures = {
+  popup?: boolean
+  noopener?: boolean
+  noreferrer?: boolean
+} & XOR<{ width?: number }, { innerWidth?: number }>
+  & XOR<{ height?: number }, { innerHeight?: number }>
+  & XOR<{ left?: number }, { screenX?: number }>
+  & XOR<{ top?: number }, { screenY?: number }>
+```
+
+## Parameters
+
+### `to`
+
+**Type**: [`RouteLocationRaw`](https://router.vuejs.org/api/interfaces/RouteLocationOptions.html#Interface-RouteLocationOptions) | `undefined` | `null`
+
+**Default**: `'/'`
+
+`to` can be a plain string or a route object to redirect to. When passed as `undefined` or `null`, it will default to `'/'`.
+
+#### Example
+
+```ts
+// Passing the URL directly will redirect to the '/blog' page
+await navigateTo('/blog')
+
+// Using the route object, will redirect to the route with the name 'blog'
+await navigateTo({ name: 'blog' })
+
+// Redirects to the 'product' route while passing a parameter (id = 1) using the route object.
+await navigateTo({ name: 'product', params: { id: 1 } })
+```
+
+### `options` (optional)
+
+**Type**: `NavigateToOptions`
+
+An object accepting the following properties:
+
+- `replace`
+
+  - **Type**: `boolean`
+  - **Default**: `false`
+  - By default, `navigateTo` pushes the given route into the Vue Router's instance on the client side.
+
+    This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.
+
+- `redirectCode`
+
+  - **Type**: `number`
+  - **Default**: `302`
+
+  - `navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) by default when the redirection takes place on the server side.
+
+    This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) can be used for permanent redirections.
+
+- `external`
+
+  - **Type**: `boolean`
+  - **Default**: `false`
+
+  - Allows navigating to an external URL when set to `true`. Otherwise, `navigateTo` will throw an error, as external navigation is not allowed by default.
+
+- `open`
+
+  - **Type**: `OpenOptions`
+  - Allows navigating to the URL using the [open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) method of the window. This option is only applicable on the client side and will be ignored on the server side.
+
+    An object accepting the following properties:
+
+  - `target`
+
+    - **Type**: `string`
+    - **Default**: `'_blank'`
+
+    - A string, without whitespace, specifying the name of the browsing context the resource is being loaded into.
+
+  - `windowFeatures`
+
+    - **Type**: `OpenWindowFeatures`
+
+    - An object accepting the following properties:
+
+      | Property | Type    | Description |
+      |----------|---------|--------------|
+      | `popup`  | `boolean` | Requests a minimal popup window instead of a new tab, with UI features decided by the browser. |
+      | `width` or `innerWidth`  | `number`  | Specifies the content area's width (minimum 100 pixels), including scrollbars. |
+      | `height` or `innerHeight` | `number`  | Specifies the content area's height (minimum 100 pixels), including scrollbars. |
+      | `left` or `screenX`   | `number`  | Sets the horizontal position of the new window relative to the left edge of the screen. |
+      | `top` or `screenY`   | `number`  | Sets the vertical position of the new window relative to the top edge of the screen. |
+      | `noopener` | `boolean` | Prevents the new window from accessing the originating window via `window.opener`. |
+      | `noreferrer` | `boolean` | Prevents the Referer header from being sent and implicitly enables `noopener`. |
+
+      Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#windowfeatures) for more detailed information on the **windowFeatures** properties.

package/3.api/3.utils/on-before-route-leave.md

@@ -0,0 +1,11 @@
+---
+title: "onBeforeRouteLeave"
+description: The onBeforeRouteLeave composable allows registering a route guard within a component.
+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
+---
+
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/#onBeforeRouteLeave" title="Vue Router Docs" target="_blank"}

package/3.api/3.utils/on-before-route-update.md

@@ -0,0 +1,11 @@
+---
+title: "onBeforeRouteUpdate"
+description: The onBeforeRouteUpdate composable allows registering a route guard within a component.
+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
+---
+
+:read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/#onBeforeRouteUpdate" title="Vue Router Docs" target="_blank"}

package/3.api/3.utils/on-nuxt-ready.md

@@ -0,0 +1,25 @@
+---
+title: "onNuxtReady"
+description: The onNuxtReady composable allows running a callback after your app has finished initializing.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/ready.ts
+    size: xs
+---
+
+::important
+`onNuxtReady` only runs on the client-side. :br
+It is ideal for running code that should not block the initial rendering of your app.
+::
+
+```ts [plugins/ready.client.ts]
+export default defineNuxtPlugin(() => {
+  onNuxtReady(async () => {
+    const myAnalyticsLibrary = await import('my-big-analytics-library')
+    // do something with myAnalyticsLibrary
+  })
+})
+```
+
+It is 'safe' to run even after your app has initialized. In this case, then the code will be registered to run in the next idle callback.

package/3.api/3.utils/prefetch-components.md

@@ -0,0 +1,28 @@
+---
+title: 'prefetchComponents'
+description: Nuxt provides utilities to give you control over prefetching components.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/preload.ts
+    size: xs
+---
+
+
+Prefetching component downloads the code in the background, this is based on the assumption that the component will likely be used for rendering, enabling the component to load instantly if and when the user requests it. The component is downloaded and cached for anticipated future use without the user making an explicit request for it.
+
+Use `prefetchComponents` to manually prefetch individual components that have been registered globally in your Nuxt app. By default Nuxt registers these as async components. You must use the Pascal-cased version of the component name.
+
+```ts
+await prefetchComponents('MyGlobalComponent')
+
+await prefetchComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
+```
+
+::note
+Current implementation behaves exactly the same as [`preloadComponents`](/docs/api/utils/preload-components) by preloading components instead of just prefetching we are working to improve this behavior.
+::
+
+::note
+On server, `prefetchComponents` will have no effect.
+::

package/3.api/3.utils/preload-components.md

@@ -0,0 +1,23 @@
+---
+title: 'preloadComponents'
+description: Nuxt provides utilities to give you control over preloading components.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/preload.ts
+    size: xs
+---
+
+Preloading components loads components that your page will need very soon, which you want to start loading early in rendering lifecycle. This ensures they are available earlier and are less likely to block the page's render, improving performance.
+
+Use `preloadComponents` to manually preload individual components that have been registered globally in your Nuxt app. By default Nuxt registers these as async components. You must use the Pascal-cased version of the component name.
+
+```js
+await preloadComponents('MyGlobalComponent')
+
+await preloadComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
+```
+
+::note
+On server, `preloadComponents` will have no effect.
+::

package/3.api/3.utils/preload-route-components.md

@@ -0,0 +1,41 @@
+---
+title: 'preloadRouteComponents'
+description: preloadRouteComponents allows you to manually preload individual pages in your Nuxt app.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/preload.ts
+    size: xs
+---
+
+Preloading routes loads the components of a given route that the user might navigate to in future. This ensures that the components are available earlier and less likely to block the navigation, improving performance.
+
+::tip{icon="i-lucide-rocket"}
+Nuxt already automatically preloads the necessary routes if you're using the `NuxtLink` component.
+::
+
+:read-more{to="/docs/api/components/nuxt-link"}
+
+## Example
+
+Preload a route when using `navigateTo`.
+
+```ts
+// we don't await this async function, to avoid blocking rendering
+// this component's setup function
+preloadRouteComponents('/dashboard')
+
+const submit = async () => {
+  const results = await $fetch('/api/authentication')
+
+  if (results.token) {
+    await navigateTo('/dashboard')
+  }
+}
+```
+
+:read-more{to="/docs/api/utils/navigate-to"}
+
+::note
+On server, `preloadRouteComponents` will have no effect.
+::