@nuxt/docs 3.20.1 → 3.21.0

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

@@ -0,0 +1,94 @@
+---
+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#Properties-currentRoute-" target="_blank"}
+Read `vue-router` documentation about the `Router` interface.
+::
+
+## Basic Manipulation
+
+- [`addRoute()`](https://router.vuejs.org/api/interfaces/router#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#removeRoute-): Remove an existing route by its name.
+- [`getRoutes()`](https://router.vuejs.org/api/interfaces/router#getRoutes-): Get a full list of all the route records.
+- [`hasRoute()`](https://router.vuejs.org/api/interfaces/router#hasRoute-): Checks if a route with a given name exists.
+- [`resolve()`](https://router.vuejs.org/api/interfaces/router#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/3.x/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#back-): Go back in history if possible, same as `router.go(-1)`.
+- [`forward()`](https://router.vuejs.org/api/interfaces/router#forward-): Go forward in history if possible, same as `router.go(1)`.
+- [`go()`](https://router.vuejs.org/api/interfaces/router#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#push-): Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use [`navigateTo`](/docs/3.x/api/utils/navigate-to) instead.**
+- [`replace()`](https://router.vuejs.org/api/interfaces/router#replace-): Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use [`navigateTo`](/docs/3.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/3.x/directory-structure/middleware"}
+
+## Promise and Error Handling
+
+- [`isReady()`](https://router.vuejs.org/api/interfaces/router#isReady-): Returns a Promise that resolves when the router has completed the initial navigation.
+- [`onError`](https://router.vuejs.org/api/interfaces/router#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#Methods-" title="Vue Router Docs" target="_blank"}
+
+## Universal Router Instance
+
+If you do not have a `pages/` folder, then [`useRouter`](/docs/3.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`.

package/{3.api → 4.api}/2.composables/use-runtime-config.md

@@ -22,7 +22,7 @@ export default defineEventHandler((event) => {
 })
 ```
 
-:read-more{to="/docs/guide/going-further/runtime-config"}
+:read-more{to="/docs/3.x/guide/going-further/runtime-config"}
 
 ## Define Runtime Config
 
@@ -48,7 +48,7 @@ export default defineNuxtConfig({
 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"}
+:read-more{to="/docs/3.x/guide/going-further/runtime-config"}
 
 ## Access Runtime Config
 
@@ -76,7 +76,7 @@ In this example, since `apiBase` is defined within the `public` namespace, it is
 
 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"}
+:read-more{to="/docs/3.x/guide/going-further/runtime-config"}
 
 ### Using the `.env` File
 
@@ -95,7 +95,7 @@ Any environment variables set within `.env` file are accessed using `process.env
 In **production runtime**, you should use platform environment variables and `.env` is not used.
 ::
 
-:read-more{to="/docs/guide/directory-structure/env"}
+:read-more{to="/docs/3.x/directory-structure/env"}
 
 ## `app` namespace
 
@@ -139,4 +139,4 @@ export default defineEventHandler((event) => {
 })
 ```
 
-:read-more{to="/docs/guide/going-further/runtime-config"}
+:read-more{to="/docs/3.x/guide/going-further/runtime-config"}

package/{3.api → 4.api}/2.composables/use-seo-meta.md

@@ -14,7 +14,7 @@ This helps you avoid common mistakes, such as using `name` instead of `property`
 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"}
+:read-more{to="/docs/3.x/getting-started/seo-meta"}
 
 ## Usage
 
@@ -48,7 +48,7 @@ useSeoMeta({
 
 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"}
+:read-more{to="/docs/3.x/getting-started/seo-meta"}
 
 ## Performance
 

package/{3.api → 4.api}/2.composables/use-server-seo-meta.md

@@ -10,7 +10,7 @@ links:
 
 Just like [`useSeoMeta`](/docs/3.x/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"}
+:read-more{to="/docs/3.x/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/3.x/api/composables/use-server-seo-meta) as a performance-focused utility that will not do anything (or return a `head` object) on the client.
 
@@ -24,4 +24,4 @@ useServerSeoMeta({
 
 Parameters are exactly the same as with [`useSeoMeta`](/docs/3.x/api/composables/use-seo-meta)
 
-:read-more{to="/docs/getting-started/seo-meta"}
+:read-more{to="/docs/3.x/getting-started/seo-meta"}

package/{3.api → 4.api}/2.composables/use-state.md

@@ -15,7 +15,7 @@ links:
 const count = useState('counter', () => Math.round(Math.random() * 100))
 ```
 
-:read-more{to="/docs/getting-started/state-management"}
+:read-more{to="/docs/3.x/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.
@@ -29,7 +29,7 @@ Because the data inside `useState` will be serialized to JSON, it is important t
 
 ## 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.
+If you don't need your state to be deeply reactive, you can combine `useState` with [`shallowRef`](https://vuejs.org/api/reactivity-advanced#shallowref). This can improve performance when your state contains large objects and arrays.
 
 ```ts
 const state = useState('my-shallow-state', () => shallowRef({ deep: 'not reactive' }))
@@ -46,3 +46,13 @@ export function 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/3.x/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
+
+## Troubleshooting
+
+### `Cannot stringify arbitrary non-POJOs`
+
+This error occurs when you try to store a non-serializable payload with `useState`, such as class instances.
+
+If you want to store class instances with `useState` that are not supported by Nuxt, you can use [`definePayloadPlugin`](/docs/3.x/api/composables/use-nuxt-app#custom-reducerreviver) to add a custom serializer and deserializer for your classes.
+
+:read-more{to="/docs/3.x/api/composables/use-nuxt-app#payload"}

package/{3.api → 4.api}/3.utils/$fetch.md

@@ -11,7 +11,7 @@ links:
 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/3.x/guide/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.
+During server-side rendering, calling `$fetch` to fetch your internal [API routes](/docs/3.x/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.
 ::
 
 ::note{color="blue" icon="i-lucide-info"}
@@ -35,7 +35,7 @@ const { data } = await useFetch('/api/item')
 </script>
 ```
 
-:read-more{to="/docs/getting-started/data-fetching"}
+:read-more{to="/docs/3.x/getting-started/data-fetching"}
 
 You can use `$fetch` in any methods that are executed only on client-side.
 

package/{3.api → 4.api}/3.utils/abort-navigation.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::warning
-`abortNavigation` is only usable inside a [route middleware handler](/docs/3.x/guide/directory-structure/middleware).
+`abortNavigation` is only usable inside a [route middleware handler](/docs/3.x/directory-structure/middleware).
 ::
 
 ## Type
@@ -22,7 +22,7 @@ export function abortNavigation (err?: Error | string): false
 
 ### `err`
 
-- **Type**: [`Error`](https://developer.mozilla.org/pl/docs/Web/JavaScript/Reference/Global_Objects/Error) | `string`
+- **Type**: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | `string`
 
   Optional error to be thrown by `abortNavigation`.
 
@@ -60,7 +60,7 @@ export default defineNuxtRouteMiddleware((to, from) => {
 
 ### `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:
+You can pass the error as an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, e.g. caught by the `catch`-block:
 
 ```ts [middleware/auth.ts]
 export default defineNuxtRouteMiddleware((to, from) => {

package/{3.api → 4.api}/3.utils/add-route-middleware.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::note
-Route middleware are navigation guards stored in the [`middleware/`](/docs/3.x/guide/directory-structure/middleware) directory of your Nuxt application (unless [set otherwise](/docs/3.x/api/nuxt-config#middleware)).
+Route middleware are navigation guards stored in the [`middleware/`](/docs/3.x/directory-structure/middleware) directory of your Nuxt application (unless [set otherwise](/docs/3.x/api/nuxt-config#middleware)).
 ::
 
 ## Type

package/{3.api → 4.api}/3.utils/call-once.md

@@ -1,8 +1,6 @@
 ---
 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
@@ -54,11 +52,11 @@ await callOnce(async () => {
 `navigation` mode is available since [Nuxt v3.15](/blog/v3-15).
 ::
 
-::tip{to="/docs/getting-started/state-management#usage-with-pinia"}
+::tip{to="/docs/3.x/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"}
+:read-more{to="/docs/3.x/getting-started/state-management"}
 
 ::warning
 Note that `callOnce` doesn't return anything. You should use [`useAsyncData`](/docs/3.x/api/composables/use-async-data) or [`useFetch`](/docs/3.x/api/composables/use-fetch) if you want to do data fetching during SSR.

package/{3.api → 4.api}/3.utils/clear-error.md

@@ -26,4 +26,4 @@ clearError({ redirect: '/homepage' })
 
 Errors are set in state using [`useError()`](/docs/3.x/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"}
+:read-more{to="/docs/3.x/getting-started/error-handling"}

package/{3.api → 4.api}/3.utils/create-error.md

@@ -12,9 +12,9 @@ You can use this function to create an error object with additional metadata. It
 
 ## Parameters
 
-- `err`: `string | { cause, data, message, name, stack, statusCode, statusMessage, fatal }`
+- `err`: `string | { cause, data, message, name, stack, status, statusText, 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.
+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 `status` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `status`, `message`, and other error properties.
 
 ## In Vue App
 
@@ -30,7 +30,7 @@ If you throw an error created with `createError`:
 const route = useRoute()
 const { data } = await useFetch(`/api/movies/${route.params.slug}`)
 if (!data.value) {
-  throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
+  throw createError({ status: 404, statusText: 'Page Not Found' })
 }
 </script>
 ```
@@ -44,12 +44,12 @@ Use `createError` to trigger error handling in server API routes.
 ```ts [server/api/error.ts]
 export default eventHandler(() => {
   throw createError({
-    statusCode: 404,
-    statusMessage: 'Page Not Found',
+    status: 404,
+    statusText: '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.
+In API routes, using `createError` by passing an object with a short `statusText` 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"}
+:read-more{to="/docs/3.x/getting-started/error-handling"}

package/{3.api → 4.api}/3.utils/define-lazy-hydration-component.md

@@ -4,7 +4,7 @@ description: 'Define a lazy hydration component with a specific strategy.'
 links:
   - label: Source
     icon: i-simple-icons-github
-    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/components/plugins/lazy-hydration-macro-transform.ts
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/plugins/lazy-hydration-macro-transform.ts
     size: xs
 ---
 
@@ -42,7 +42,7 @@ Read more about the options for `hydrate-on-visible`.
 ::
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-visible).
+Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async#hydrate-on-visible).
 ::
 
 ### Idle Strategy
@@ -70,7 +70,7 @@ The `hydrateOnIdle` prop is optional. You can pass a positive number to specify
 Idle strategy is for components that can be hydrated when the browser is idle.
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-idle).
+Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async#hydrate-on-idle).
 ::
 
 ### Interaction Strategy
@@ -99,7 +99,7 @@ const LazyHydrationMyComponent = defineLazyHydrationComponent(
 The `hydrateOnInteraction` prop is optional. If you do not pass an event or a list of events, it defaults to hydrating on `pointerenter`, `click`, and `focus`.
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-interaction).
+Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async#hydrate-on-interaction).
 ::
 
 ### Media Query Strategy
@@ -126,7 +126,7 @@ const LazyHydrationMyComponent = defineLazyHydrationComponent(
 ```
 
 ::note
-Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async.html#hydrate-on-media-query).
+Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async#hydrate-on-media-query).
 ::
 
 ### Time Strategy

package/{3.api → 4.api}/3.utils/define-nuxt-component.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::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.
+`defineNuxtComponent()` is a helper function for defining type safe Vue components using options API similar to [`defineComponent()`](https://vuejs.org/api/general#definecomponent). `defineNuxtComponent()` wrapper also adds support for `asyncData` and `head` component options.
 ::
 
 ::note

package/{3.api → 4.api}/3.utils/define-nuxt-plugin.md

@@ -16,7 +16,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-:read-more{to="/docs/guide/directory-structure/plugins#creating-plugins"}
+:read-more{to="/docs/3.x/directory-structure/plugins#creating-plugins"}
 
 ## Type
 
@@ -42,19 +42,19 @@ interface ObjectPlugin<T> {
 ## Parameters
 
 **plugin**: A plugin can be defined in two ways:
-1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/3.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with an potential object with a [`provide`](/docs/3.x/guide/directory-structure/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/3.x/guide/going-further/internals#the-nuxtapp-interface) instance.
+1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/3.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with a potential object with a [`provide`](/docs/3.x/directory-structure/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/3.x/guide/going-further/internals#the-nuxtapp-interface) instance.
 2. **Object Plugin**: An object that can include various properties to configure the plugin's behavior, such as `name`, `enforce`, `dependsOn`, `order`, `parallel`, `setup`, `hooks`, and `env`.
 
-| Property           | Type                                                                 | Required | Description                                                                                                     |
-| ------------------ | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
-| `name` | `string` | `false` | Optional name for the plugin, useful for debugging and dependency management. |
-| `enforce` | `'pre'` \| `'default'` \| `'post'` | `false` | Controls when the plugin runs relative to other plugins. |
-| `dependsOn` | `string[]` | `false` | Array of plugin names this plugin depends on. Ensures proper execution order. |
-| `order` | `number` | `false` | This allows more granular control over plugin order and should only be used by advanced users. **It overrides the value of `enforce` and is used to sort plugins.** |
-| `parallel` | `boolean` | `false` | Whether to execute the plugin in parallel with other parallel plugins. |
-| `setup` | `Plugin<T>`{lang="ts"}  | `false` | The main plugin function, equivalent to a function plugin. |
-| `hooks` | `Partial<RuntimeNuxtHooks>`{lang="ts"}  | `false` | Nuxt app runtime hooks to register directly. |
-| `env` | `{ islands?: boolean }`{lang="ts"}  | `false` | Set this value to `false` if you don't want the plugin to run when rendering server-only or island components. |
+| Property    | Type                                   | Required | Description                                                                                                                                                         |
+|-------------|----------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `name`      | `string`                               | `false`  | Optional name for the plugin, useful for debugging and dependency management.                                                                                       |
+| `enforce`   | `'pre'` \| `'default'` \| `'post'`     | `false`  | Controls when the plugin runs relative to other plugins.                                                                                                            |
+| `dependsOn` | `string[]`                             | `false`  | Array of plugin names this plugin depends on. Ensures proper execution order.                                                                                       |
+| `order`     | `number`                               | `false`  | This allows more granular control over plugin order and should only be used by advanced users. **It overrides the value of `enforce` and is used to sort plugins.** |
+| `parallel`  | `boolean`                              | `false`  | Whether to execute the plugin in parallel with other parallel plugins.                                                                                              |
+| `setup`     | `Plugin<T>`{lang="ts"}                 | `false`  | The main plugin function, equivalent to a function plugin.                                                                                                          |
+| `hooks`     | `Partial<RuntimeNuxtHooks>`{lang="ts"} | `false`  | Nuxt app runtime hooks to register directly.                                                                                                                        |
+| `env`       | `{ islands?: boolean }`{lang="ts"}     | `false`  | Set this value to `false` if you don't want the plugin to run when rendering server-only or island components.                                                      |
 
 :video-accordion{title="Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins" videoId="2aXZyXB1QGQ"}
 

package/{3.api → 4.api}/3.utils/define-nuxt-route-middleware.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-Route middleware are stored in the [`middleware/`](/docs/3.x/guide/directory-structure/middleware) of your Nuxt application (unless [set otherwise](/docs/3.x/api/nuxt-config#middleware)).
+Route middleware are stored in the [`middleware/`](/docs/3.x/directory-structure/middleware) of your Nuxt application (unless [set otherwise](/docs/3.x/api/nuxt-config#middleware)).
 
 ## Type
 
@@ -28,7 +28,7 @@ interface 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/type-aliases/RouteLocationNormalized.html)**.
+Learn more about available properties of `RouteLocationNormalized` in the **[Vue Router docs](https://router.vuejs.org/api/type-aliases/routelocationnormalized)**.
 
 ## Examples
 
@@ -39,7 +39,7 @@ 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' })
+    throw createError({ status: 404, statusText: 'Page Not Found' })
   }
 })
 ```

package/{3.api → 4.api}/3.utils/define-page-meta.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the [`pages/`](/docs/3.x/guide/directory-structure/pages) directory (unless [set otherwise](/docs/3.x/api/nuxt-config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application.
+`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the [`pages/`](/docs/3.x/directory-structure/pages) directory (unless [set otherwise](/docs/3.x/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">
@@ -18,7 +18,7 @@ definePageMeta({
 </script>
 ```
 
-:read-more{to="/docs/guide/directory-structure/pages#page-metadata"}
+:read-more{to="/docs/3.x/directory-structure/pages#page-metadata"}
 
 ## Type
 
@@ -32,6 +32,7 @@ interface PageMeta {
   path?: string
   props?: RouteRecordRaw['props']
   alias?: string | string[]
+  groups?: string[]
   pageTransition?: boolean | TransitionProps
   layoutTransition?: boolean | TransitionProps
   viewTransition?: boolean | 'always'
@@ -56,13 +57,13 @@ interface PageMeta {
 
   - **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/3.x/guide/directory-structure/pages).
+    You may define a name for this page's route. By default, name is generated based on path inside the [`pages/` directory](/docs/3.x/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.
+    You may define a [custom regular expression](/docs/3.x/api/utils/define-page-meta#using-a-custom-regular-expression) if you have a more complex pattern than can be expressed with the file name.
 
   **`props`**
   
@@ -76,11 +77,17 @@ interface PageMeta {
 
     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.
 
+  **`groups`**
+
+  - **Type**: `string[]`
+
+    Route groups the page belongs to, based on the folder structure. Automatically populated for pages within [route groups](/docs/3.x/guide/directory-structure/app/pages#route-groups).
+
   **`keepalive`**
 
-  - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components.html#keepalive)
+  - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components#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.
+    Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive) for a fine-grained control.
 
   **`key`**
 
@@ -96,19 +103,19 @@ interface PageMeta {
 
   **`layoutTransition`**
 
-  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition)
+  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components#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>`
+  - **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/navigationguard) | `Array<MiddlewareKey | NavigationGuard>`
 
-    Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/3.x/guide/directory-structure/middleware).
+    Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/3.x/directory-structure/middleware).
 
   **`pageTransition`**
 
-  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components.html#transition)
+  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
 
     Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition.
 
@@ -122,7 +129,7 @@ interface PageMeta {
 
   **`redirect`**
 
-  - **Type**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/redirect-and-alias.html#redirect-and-alias)
+  - **Type**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/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.
 
@@ -130,19 +137,19 @@ interface PageMeta {
 
   - **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).
+    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 `status`/`statusText` 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/3.x/guide/recipes/custom-routing#using-approuteroptions)) for more info.
+    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 `~/router.options.ts` (see [custom routing](/docs/3.x/guide/recipes/custom-routing#using-routeroptions)) 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/3.x/guide/directory-structure/pages/#typing-custom-metadata).
+    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/3.x/directory-structure/pages/#typing-custom-metadata).
 
 ## Examples
 
@@ -215,11 +222,11 @@ definePageMeta({
 </script>
 ```
 
-For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/guide/essentials/route-matching-syntax.html).
+For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/guide/essentials/route-matching-syntax).
 
 ### Defining Layout
 
-You can define the layout that matches the layout's file name located (by default) in the [`layouts/` directory](/docs/3.x/guide/directory-structure/layouts). You can also disable the layout by setting the `layout` to `false`:
+You can define the layout that matches the layout's file name located (by default) in the [`layouts/` directory](/docs/3.x/directory-structure/layouts). You can also disable the layout by setting the `layout` to `false`:
 
 ```vue [pages/some-page.vue]
 <script setup lang="ts">

package/{3.api → 4.api}/3.utils/define-route-rules.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-::read-more{to="/docs/guide/going-further/experimental-features#inlinerouterules" icon="i-lucide-star"}
+::read-more{to="/docs/3.x/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`.
 ::
 
@@ -47,6 +47,6 @@ When running [`nuxt build`](/docs/3.x/api/commands/build), the home page will be
 
 For more control, such as if you are using a custom `path` or `alias` set in the page's [`definePageMeta`](/docs/3.x/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{to="/docs/3.x/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
 Read more about the `routeRules`.
 ::