@nuxt/docs 4.2.0 → 4.2.2

package/7.migration/2.configuration.md

@@ -140,7 +140,7 @@ If you are a module author, you can check out [more information about module com
 
 The `static/` (for storing static assets) has been renamed to `public/`. You can either rename your `static` directory to `public`, or keep the name by setting `dir.public` in your `nuxt.config`.
 
-:read-more{to="/docs/4.x/guide/directory-structure/public"}
+:read-more{to="/docs/4.x/directory-structure/public"}
 
 ## TypeScript
 
@@ -183,7 +183,7 @@ Nuxt can type-check your app using [`vue-tsc`](https://github.com/vuejs/language
 
 There are a number of changes to what is recommended Vue best practice, as well as a number of breaking changes between Vue 2 and 3.
 
-It is recommended to read the [Vue 3 migration guide](https://v3-migration.vuejs.org) and in particular the [breaking changes list](https://v3-migration.vuejs.org/breaking-changes).
+It is recommended to read the [Vue 3 migration guide](https://v3-migration.vuejs.org) and in particular the [breaking changes list](https://v3-migration.vuejs.org/breaking-changes/).
 
 It is not currently possible to use the [Vue 3 migration build](https://v3-migration.vuejs.org/migration-build.html) with Nuxt 3.
 
@@ -227,7 +227,7 @@ export const useMainStore = defineStore('main', {
 })
 ```
 
-Create a [plugin](/docs/4.x/guide/directory-structure/plugins) file to globalize your store:
+Create a [plugin](/docs/4.x/directory-structure/app/plugins) file to globalize your store:
 
 ```ts [app/plugins/pinia.ts]
 import { useMainStore } from '~/store'

package/7.migration/20.module-authors.md

@@ -17,7 +17,7 @@ Explore Nuxt 3 compatible modules.
 
 Nuxt 3 plugins are **not** fully backward compatible with Nuxt 2.
 
-:read-more{to="/docs/4.x/guide/directory-structure/plugins"}
+:read-more{to="/docs/4.x/directory-structure/app/plugins"}
 
 ### Vue Compatibility
 

package/7.migration/3.auto-imports.md

@@ -11,7 +11,7 @@ In the rest of the migration documentation, you will notice that key Nuxt and Vu
 
 ## Migration
 
-1. If you have been using `@nuxt/components` in Nuxt 2, you can remove `components: true` in your `nuxt.config`. If you had a more complex setup, then note that the component options have changed somewhat. See the [components documentation](/docs/4.x/guide/directory-structure/app/components) for more information.
+1. If you have been using `@nuxt/components` in Nuxt 2, you can remove `components: true` in your `nuxt.config`. If you had a more complex setup, then note that the component options have changed somewhat. See the [components documentation](/docs/4.x/directory-structure/app/components) for more information.
 
 ::tip
 You can look at `.nuxt/types/components.d.ts` and `.nuxt/types/imports.d.ts` to see how Nuxt has resolved your components and composable auto-imports.

package/7.migration/5.plugins-and-middleware.md

@@ -31,7 +31,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 
 ::
 
-:read-more{to="/docs/4.x/guide/directory-structure/plugins"}
+:read-more{to="/docs/4.x/directory-structure/app/plugins"}
 
 ::read-more{to="/docs/4.x/api/composables/use-nuxt-app"}
 Read more about the format of `nuxtApp`.
@@ -72,7 +72,7 @@ Much like Nuxt 2, route middleware placed in your `~/middleware` folder is autom
 
 `navigateTo` is one of a number of route helper functions.
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/middleware"}
+:read-more{to="/docs/4.x/directory-structure/app/middleware"}
 
 ### Migration
 

package/7.migration/6.pages-and-layouts.md

@@ -13,19 +13,19 @@ If you don't have an `app.vue` file in your source directory, Nuxt will use its
 
 This file is a great place to put any custom code that needs to be run once when your app starts up, as well as any components that are present on every page of your app. For example, if you only have one layout, you can move this to `app.vue` instead.
 
-:read-more{to="/docs/4.x/guide/directory-structure/app"}
+:read-more{to="/docs/4.x/directory-structure/app/app"}
 
 :link-example{to="/docs/4.x/examples/hello-world"}
 
 ### Migration
 
-Consider creating an `app.vue` file and including any logic that needs to run once at the top-level of your app. You can check out [an example here](/docs/4.x/guide/directory-structure/app).
+Consider creating an `app.vue` file and including any logic that needs to run once at the top-level of your app. You can check out [an example here](/docs/4.x/directory-structure/app/app).
 
 ## Layouts
 
 If you are using layouts in your app for multiple pages, there is only a slight change required.
 
-In Nuxt 2, the `<Nuxt>` component is used within a layout to render the current page. In Nuxt 3, layouts use slots instead, so you will have to replace that component with a `<slot />`. This also allows advanced use cases with named and scoped slots. [Read more about layouts](/docs/4.x/guide/directory-structure/app/layouts).
+In Nuxt 2, the `<Nuxt>` component is used within a layout to render the current page. In Nuxt 3, layouts use slots instead, so you will have to replace that component with a `<slot />`. This also allows advanced use cases with named and scoped slots. [Read more about layouts](/docs/4.x/directory-structure/app/layouts).
 
 You will also need to change how you define the layout used by a page using the `definePageMeta` compiler macro. Layouts will be kebab-cased. So `app/layouts/customLayout.vue` becomes `custom-layout` when referenced in your page.
 
@@ -54,7 +54,7 @@ You will also need to change how you define the layout used by a page using the
     - }
       </script>
     ```
-3. Move `~/layouts/_error.vue` to `~/error.vue`. See [the error handling docs](/docs/4.x/getting-started/error-handling). If you want to ensure that this page uses a layout, you can use [`<NuxtLayout>`](/docs/4.x/guide/directory-structure/app/layouts) directly within `error.vue`:
+3. Move `~/layouts/_error.vue` to `~/error.vue`. See [the error handling docs](/docs/4.x/getting-started/error-handling). If you want to ensure that this page uses a layout, you can use [`<NuxtLayout>`](/docs/4.x/directory-structure/app/layouts) directly within `error.vue`:
     ```vue [error.vue]
     <template>
       <div>
@@ -67,7 +67,7 @@ You will also need to change how you define the layout used by a page using the
 
 ## Pages
 
-Nuxt 3 ships with an optional `vue-router` integration triggered by the existence of a [`app/pages/`](/docs/4.x/guide/directory-structure/app/pages) directory in your source directory. If you only have a single page, you may consider instead moving it to `app.vue` for a lighter build.
+Nuxt 3 ships with an optional `vue-router` integration triggered by the existence of a [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory in your source directory. If you only have a single page, you may consider instead moving it to `app.vue` for a lighter build.
 
 ### Dynamic Routes
 
@@ -84,7 +84,7 @@ In Nuxt 2, you will have defined any nested routes (with parent and child compon
 
 If you were passing a custom page key or keep-alive props to `<Nuxt>`, you will now use `definePageMeta` to set these options.
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/pages#special-metadata"}
+:read-more{to="/docs/4.x/directory-structure/app/pages#special-metadata"}
 
 ### Page and Layout Transitions
 

package/README.md

@@ -4,7 +4,7 @@ navigation: false
 
 # Nuxt Docs
 
-This repository contains the documentation of Nuxt hosted on <https://nuxt.com/docs>
+This repository contains the documentation of Nuxt, hosted on <https://nuxt.com/docs/4.x/getting-started/introduction>
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",

package/2.guide/1.directory-structure/3.tsconfig.md

@@ -1,38 +0,0 @@
----
-title: "tsconfig.json"
-description: "Nuxt generates multiple TypeScript configuration files with sensible defaults and your aliases."
-head.title: "tsconfig.json"
-navigation.icon: i-vscode-icons-file-type-tsconfig
----
-
-Nuxt [automatically generates](/docs/4.x/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
-
-You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
-
-```json [tsconfig.json]
-{
-  "files": [],
-  "references": [
-    {
-      "path": "./.nuxt/tsconfig.app.json"
-    },
-    {
-      "path": "./.nuxt/tsconfig.server.json"
-    },
-    {
-      "path": "./.nuxt/tsconfig.shared.json"
-    },
-    {
-      "path": "./.nuxt/tsconfig.node.json"
-    }
-  ]
-}
-```
-
-::note
-As you need to, you can customize the contents of this file. However, it is recommended that you don't overwrite `target`, `module` and `moduleResolution`.
-::
-
-::note
-If you need to customize your `paths`, this will override the auto-generated path aliases. Instead, we recommend that you add any path aliases you need to the [`alias`](/docs/4.x/api/nuxt-config#alias) property within your `nuxt.config`, where they will get picked up and added to the auto-generated `tsconfig`.
-::

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

@@ -1,183 +0,0 @@
----
-title: 'useCookie'
-description: useCookie is an SSR-friendly composable to read and write cookies.
-links:
-  - label: Source
-    icon: i-simple-icons-github
-    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/composables/cookie.ts
-    size: xs
----
-
-## Usage
-
-Within your pages, components, and plugins, you can use `useCookie` to read and write cookies in an SSR-friendly way.
-
-```ts
-const cookie = useCookie(name, options)
-```
-
-::note
-`useCookie` only works in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).
-::
-
-::tip
-The returned ref will automatically serialize and deserialize cookie values to JSON.
-::
-
-## Type
-
-```ts [Signature]
-import type { Ref } from 'vue'
-import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'
-
-export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
-  decode?(value: string): T
-  encode?(value: T): string
-  default?: () => T | Ref<T>
-  watch?: boolean | 'shallow'
-  readonly?: boolean
-}
-
-export interface CookieRef<T> extends Ref<T> {}
-
-export function useCookie<T = string | null | undefined> (
-  name: string,
-  options?: CookieOptions<T>
-): CookieRef<T>
-```
-
-## Parameters
-
-`name`: The name of the cookie.
-
-`options`: Options to control cookie behavior. The object can have the following properties:
-
-Most of the options will be directly passed to the [cookie](https://github.com/jshttp/cookie) package.
-
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `decode` | `(value: string) => T` | `decodeURIComponent` + [destr](https://github.com/unjs/destr). | Custom function to decode the cookie value.  Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object. <br/> **Note:** If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value. |
-| `encode` | `(value: T) => string` | `JSON.stringify` + `encodeURIComponent` | Custom function to encode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value. |
-| `default` | `() => T \| Ref<T>` | `undefined` | Function returning the default value if the cookie does not exist.  The function can also return a `Ref`. |
-| `watch` | `boolean \| 'shallow'` | `true`  | Whether to watch for changes and update the cookie. `true` for deep watch, `'shallow'` for shallow watch, i.e. data changes for only top level properties, `false` to disable. <br/> **Note:** Refresh `useCookie` values manually when a cookie has changed with [`refreshCookie`](/docs/4.x/api/utils/refresh-cookie). |
-| `readonly` | `boolean` | `false` | If `true`, disables writing to the cookie. |
-| `maxAge` | `number` | `undefined` | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2). The given number will be converted to an integer by rounding down. By default, no maximum age is set. |
-| `expires` | `Date` | `undefined` | Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br/> **Note:** The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and `maxAge` is set, then `maxAge` takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br/>If neither of `expires` and `maxAge` is set, the cookie will be session-only and removed when the user closes their browser. |
-| `httpOnly` | `boolean` | `false` | Sets the HttpOnly attribute. <br/> **Note:** Be careful when setting this to `true`, as compliant clients will not allow client-side JavaScript to see the cookie in `document.cookie`. |
-| `secure` | `boolean` | `false` | Sets the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). <br/>**Note:** Be careful when setting this to `true`, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors. |
-| `partitioned` | `boolean` | `false` | Sets the [`Partitioned` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1). <br/>**Note:** This is an attribute that has not yet been fully standardized, and may change in the future. <br/>This also means many clients may ignore this attribute until they understand it.<br/>More information can be found in the [proposal](https://github.com/privacycg/CHIPS). |
-| `domain` | `string` | `undefined` | Sets the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3). By default, no domain is set, and most clients will consider applying the cookie only to the current domain. |
-| `path` | `string` | `'/'` | Sets the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4). |
-| `sameSite` | `boolean \| string` | `undefined` | Sets the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7). <br/>- `true` will set the `SameSite` attribute to `Strict` for strict same-site enforcement.<br/>- `false` will not set the `SameSite` attribute.<br/>- `'lax'` will set the `SameSite` attribute to `Lax` for lax same-site enforcement.<br/>- `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.<br/>- `'strict'` will set the `SameSite` attribute to `Strict` for strict same-site enforcement. |
-
-## Return Values
-
-Returns a Vue `Ref<T>` representing the cookie value. Updating the ref will update the cookie (unless `readonly` is set). The ref is SSR-friendly and will work on both client and server.
-
-## Examples
-
-### Basic Usage
-
-The example below creates a cookie called `counter`. If the cookie doesn't exist, it is initially set to a random value. Whenever we update the `counter` variable, the cookie will be updated accordingly.
-
-```vue [app/app.vue]
-<script setup lang="ts">
-const counter = useCookie('counter')
-
-counter.value ||= Math.round(Math.random() * 1000)
-</script>
-
-<template>
-  <div>
-    <h1>Counter: {{ counter || '-' }}</h1>
-    <button @click="counter = null">
-      reset
-    </button>
-    <button @click="counter--">
-      -
-    </button>
-    <button @click="counter++">
-      +
-    </button>
-  </div>
-</template>
-```
-
-### Readonly Cookies
-
-```vue
-<script setup lang="ts">
-const user = useCookie(
-  'userInfo',
-  {
-    default: () => ({ score: -1 }),
-    watch: false,
-  },
-)
-
-if (user.value) {
-  // the actual `userInfo` cookie will not be updated
-  user.value.score++
-}
-</script>
-
-<template>
-  <div>User score: {{ user?.score }}</div>
-</template>
-```
-
-### Writable Cookies
-
-```vue
-<script setup lang="ts">
-const list = useCookie(
-  'list',
-  {
-    default: () => [],
-    watch: 'shallow',
-  },
-)
-
-function add () {
-  list.value?.push(Math.round(Math.random() * 1000))
-  // list cookie won't be updated with this change
-}
-
-function save () {
-  // the actual `list` cookie will be updated
-  list.value &&= [...list.value]
-}
-</script>
-
-<template>
-  <div>
-    <h1>List</h1>
-    <pre>{{ list }}</pre>
-    <button @click="add">
-      Add
-    </button>
-    <button @click="save">
-      Save
-    </button>
-  </div>
-</template>
-```
-
-### Cookies in API Routes
-
-You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.
-
-```ts [server/api/counter.ts]
-export default defineEventHandler((event) => {
-  // Read counter cookie
-  let counter = getCookie(event, 'counter') || 0
-
-  // Increase counter cookie by 1
-  setCookie(event, 'counter', ++counter)
-
-  // Send JSON response
-  return { counter }
-})
-```
-
-:link-example{to="/docs/4.x/examples/advanced/use-cookie"}

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

@@ -1,69 +0,0 @@
----
-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/4.x/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/4.x/api/composables/use-head-safe).
-
-:read-more{to="/docs/4.x/getting-started/seo-meta"}
-
-## Type
-
-```ts [Signature]
-export function useHead (meta: MaybeComputedRef<MetaObject>): void
-```
-
-Below are the non-reactive types for [`useHead`](/docs/4.x/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-lazy-async-data.md

@@ -1,47 +0,0 @@
----
-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/4.x/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/4.x/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/4.x/api/composables/use-async-data).
-::
-
-:read-more{to="/docs/4.x/api/composables/use-async-data"}
-
-## Example
-
-```vue [app/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/4.x/getting-started/data-fetching"}

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

@@ -1,55 +0,0 @@
----
-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/4.x/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` provides a wrapper around [`useFetch`](/docs/4.x/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/4.x/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/4.x/api/composables/use-fetch"}
-
-## Example
-
-```vue [app/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/4.x/getting-started/data-fetching"}

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

@@ -1,94 +0,0 @@
----
-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 [app/pages/index.vue]
-<script setup lang="ts">
-const router = useRouter()
-</script>
-```
-
-If you only need the router instance within your template, use `$router`:
-
-```vue [app/pages/index.vue]
-<template>
-  <button @click="$router.back()">
-    Back
-  </button>
-</template>
-```
-
-If you have a `app/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/4.x/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/4.x/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/4.x/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/4.x/guide/directory-structure/app/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 `app/pages/` folder, then [`useRouter`](/docs/4.x/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`.