@nuxt/docs 4.2.0 → 4.2.1

package/2.guide/3.going-further/3.modules.md

@@ -224,7 +224,7 @@ Modules, like everything in a Nuxt configuration, aren't included in your applic
 Inside the runtime directory, you can provide any kind of assets related to the Nuxt App:
 - Vue components
 - Composables
-- [Nuxt plugins](/docs/4.x/guide/directory-structure/plugins)
+- [Nuxt plugins](/docs/4.x/guide/directory-structure/app/plugins)
 
 To the [server engine](/docs/4.x/guide/concepts/server-engine), Nitro:
 - API routes
@@ -653,6 +653,19 @@ export default defineNuxtModule({
 })
 ```
 
+#### Updating Templates
+
+If you need to update your templates/virtual files, you can leverage the `updateTemplates` utility like this:
+
+```ts
+nuxt.hook('builder:watch', (event, path) => {
+  if (path.includes('my-module-feature.config')) {
+    // This will reload the template that you registered
+    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
+  }
+})
+```
+
 #### Adding Type Declarations
 
 You might also want to add a type declaration to the user's project (for example, to augment a Nuxt interface
@@ -691,19 +704,73 @@ nuxt.hook('prepare:types', ({ references }) => {
 })
 ```
 
-##### Updating Templates
+#### Extending `tsconfig.json`
+
+There are multiple ways to extend the TypeScript configuration of the user's project from your module.
 
-If you need to update your templates/virtual files, you can leverage the `updateTemplates` utility like this :
+The simplest way is to modify the Nuxt configuration directly like this:
 
+<!-- @case-police-ignore tsConfig -->
 ```ts
-nuxt.hook('builder:watch', (event, path) => {
-  if (path.includes('my-module-feature.config')) {
-    // This will reload the template that you registered
-    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
-  }
+// extend tsconfig.app.json
+nuxt.options.typescript.tsConfig.include ??= []
+nuxt.options.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.shared.json
+nuxt.options.typescript.sharedTsConfig.include ??= []
+nuxt.options.typescript.sharedTsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.node.json
+nuxt.options.typescript.nodeTsConfig.include ??= []
+nuxt.options.typescript.nodeTsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.server.json
+nuxt.options.nitro.typescript ??= {}
+nuxt.options.nitro.typescript.tsConfig ??= {}
+nuxt.options.nitro.typescript.tsConfig.include ??= []
+nuxt.options.nitro.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
+```
+
+Alternatively, you can use the `prepare:types` and `nitro:prepare:types` hooks to extend the TypeScript references for specific type contexts, or modify the TypeScript configuration similar to the example above.
+
+```ts
+nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences }) => {
+  // extend app context
+  references.push({ path: resolve('./augments.d.ts') })
+  // extend shared context
+  sharedReferences.push({ path: resolve('./augments.d.ts') })
+  // extend node context
+  nodeReferences.push({ path: resolve('./augments.d.ts') })
+})
+
+nuxt.hook('nitro:prepare:types', ({ references }) => {
+  // extend server context
+  references.push({ path: resolve('./augments.d.ts') })
 })
 ```
 
+::note
+TypeScript references add files to the type context [without being affected by the `exclude` option in `tsconfig.json`](https://www.typescriptlang.org/tsconfig/#exclude).
+::
+
+#### Augmenting Types From Modules
+
+Nuxt automatically includes your module's directories in the appropriate type contexts. To augment types from your module, all you need to do is place the type declaration file in the appropriate directory based on the augmented type context. Alternatively, you can [extend the TypeScript configuration](/docs/4.x/guide/going-further/modules#extending-tsconfigjson) to augment from an arbitrary location.
+
+- `my-module/runtime/` - app type context (except for the `runtime/server` directory)
+- `my-module/runtime/server/` - server type context
+- `my-module/` - node type context (except for the `runtime/` and `runtime/server` directories)
+
+```bash [Directory Structure]
+-| my-module/   # node type context
+---| runtime/   # app type context
+------| augments.app.d.ts
+------| server/ # server type context
+---------| augments.server.d.ts
+---| module.ts
+---| augments.node.d.ts
+```
+
 ### Testing
 
 Testing helps ensuring your module works as expected given various setup. Find in this section how to perform various kinds of tests against your module.
@@ -774,7 +841,7 @@ An example of such a workflow is available on [the module starter](https://githu
 
 Having a playground Nuxt application to test your module when developing it is really useful. [The module starter integrates one for that purpose](/docs/4.x/guide/going-further/modules#how-to-develop).
 
-You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
+You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack/) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
 
 After that, you should be able to reference `my-module` like in any regular project.
 
@@ -876,7 +943,7 @@ Watch Vue School video about Nuxt module types.
 
 ### Module Types
 
-**Official modules** are modules prefixed (scoped) with `@nuxt/` (e.g. [`@nuxt/content`](https://content.nuxtjs.org)). They are made and maintained actively by the Nuxt team. Like with the framework, contributions from the community are more than welcome to help make them better!
+**Official modules** are modules prefixed (scoped) with `@nuxt/` (e.g. [`@nuxt/content`](https://content.nuxt.com)). They are made and maintained actively by the Nuxt team. Like with the framework, contributions from the community are more than welcome to help make them better!
 
 **Community modules** are modules prefixed (scoped) with `@nuxtjs/` (e.g. [`@nuxtjs/tailwindcss`](https://tailwindcss.nuxtjs.org)). They are proven modules made and maintained by community members. Again, contributions are welcome from anyone.
 

package/2.guide/3.going-further/6.nuxt-app.md

@@ -9,7 +9,7 @@ links:
 
 In Nuxt, you can access runtime app context within composables, components and plugins.
 
-::read-more{to="https://v2.nuxt.com/docs/internals-glossary/context#the-context" target="_blank"}
+::read-more{to="https://v2.nuxt.com/docs/internals-glossary/context/#the-context" target="_blank"}
 In Nuxt 2, this was referred to as **Nuxt context**.
 ::
 
@@ -23,7 +23,7 @@ Jump over the `NuxtApp` interface documentation.
 
 Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
 
-Currently, the Nuxt context is only accessible in [plugins](/docs/4.x/guide/directory-structure/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/guide/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
+Currently, the Nuxt context is only accessible in [plugins](/docs/4.x/guide/directory-structure/app/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/guide/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup) (in pages and components).
 
 If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/4.x/api/composables/use-nuxt-app#runwithcontext).
 
@@ -42,7 +42,7 @@ If your composable does not always need `nuxtApp` or you simply want to check if
 
 Plugins also receive `nuxtApp` as the first argument for convenience.
 
-:read-more{to="/docs/4.x/guide/directory-structure/plugins"}
+:read-more{to="/docs/4.x/guide/directory-structure/app/plugins"}
 
 ## Providing Helpers
 
@@ -55,10 +55,10 @@ nuxtApp.provide('hello', name => `Hello ${name}!`)
 console.log(nuxtApp.$hello('name')) // Prints "Hello name!"
 ```
 
-::read-more{to="/docs/4.x/guide/directory-structure/plugins#providing-helpers"}
+::read-more{to="/docs/4.x/guide/directory-structure/app/plugins#providing-helpers"}
 It is possible to inject helpers by returning an object with a `provide` key in plugins.
 ::
 
-::read-more{to="https://v2.nuxt.com/docs/directory-structure/plugins#inject-in-root--context" target="_blank"}
+::read-more{to="https://v2.nuxt.com/docs/directory-structure/plugins/#inject-in-root--context" target="_blank"}
 In Nuxt 2 plugins, this was referred to as **inject function**.
 ::

package/2.guide/3.going-further/7.layers.md

@@ -20,9 +20,9 @@ Additionally, certain other files in the layer directory will be auto-scanned an
 - [`app/layouts/*`](/docs/4.x/guide/directory-structure/app/layouts)  - Extend the default layouts
 - [`app/middleware/*`](/docs/4.x/guide/directory-structure/app/middleware)  - Extend the default middleware
 - [`app/pages/*`](/docs/4.x/guide/directory-structure/app/pages)        - Extend the default pages
-- [`app/plugins/*`](/docs/4.x/guide/directory-structure/plugins)        - Extend the default plugins
+- [`app/plugins/*`](/docs/4.x/guide/directory-structure/app/plugins)        - Extend the default plugins
 - [`app/utils/*`](/docs/4.x/guide/directory-structure/app/utils)   - Extend the default utils
-- [`app/app.config.ts`](/docs/4.x/guide/directory-structure/app-config)  - Extend the default app config
+- [`app/app.config.ts`](/docs/4.x/guide/directory-structure/app/app-config)  - Extend the default app config
 - [`server/*`](/docs/4.x/guide/directory-structure/server)       - Extend the default server endpoints & middleware
 - [`nuxt.config.ts`](/docs/4.x/guide/directory-structure/nuxt-config)- Extend the default nuxt config
 
@@ -68,29 +68,46 @@ Additionally, certain other files in the layer directory will be auto-scanned an
 
 ## Layer Priority
 
-When extending from multiple layers, it's important to understand the priority order:
+When extending from multiple layers, it's important to understand the override order. Layers with **higher priority** override layers with lower priority when they define the same files or components.
 
-1. **Layers in `extends`** - earlier entries have higher priority (first overrides second)
-2. **Auto-scanned local layers** from `~~/layers` directory in alphabetical order (Z overrides A)
-3. **Your project** has the highest priority in the stack - it will always override other layers
+The priority order from highest to lowest is:
 
-For example:
+1. **Your project files** - always have the highest priority
+2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
+3. **Layers in `extends`** config - first entry has higher priority than second
+
+### When to Use Each
+
+- **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
+- **`~~/layers` directory** - Use for local layers that are part of your project
+
+::tip
+If you need to control the order of auto-scanned layers, you can prefix them with numbers: `~/layers/1.z-layer`, `~/layers/2.a-layer`. This way `2.a-layer` will have higher priority than `1.z-layer`.
+::
+
+### Example
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   extends: [
-    // Highest priority (among extends)
-    './layers/base',
-    // Medium priority
-    './layers/theme',
-    // Lower priority
-    './layers/custom',
+    // Local layer outside the project
+    '../base',
+    // NPM package
+    '@my-themes/awesome',
+    // Remote repository
+    'github:my-themes/awesome#v1',
   ],
-  // Your project has the highest priority
 })
 ```
 
-If you also have auto-scanned layers like `~~/layers/a` and `~~/layers/z`, the complete override order would be: `base` > `theme` > `custom` > `z` > `a` > your project.
+If you also have `~~/layers/custom`, the priority order is:
+- Your project files (highest)
+- `~~/layers/custom`
+- `../base`
+- `@my-themes/awesome`
+- `github:my-themes/awesome#v1` (lowest)
+
+This means your project files will override any layer, and `~~/layers/custom` will override anything in `extends`.
 
 ## Starter Template
 

package/2.guide/3.going-further/9.debugging.md

@@ -36,7 +36,7 @@ It is possible to debug your Nuxt app in your IDE while you are developing it.
 
 ### Example VS Code Debug Configuration
 
-You may need to update the config below with a path to your web browser. For more information, visit the [VS Code documentation about debug configuration](https://go.microsoft.com/fwlink/?linkid=830387).
+You may need to update the config below with a path to your web browser. For more information, visit the [VS Code documentation about debug configuration](https://code.visualstudio.com/docs/debugtest/debugging#_launch-configurations).
 
 ```json5
 {

package/2.guide/4.recipes/1.custom-routing.md

@@ -17,7 +17,7 @@ If it returns `null` or `undefined`, Nuxt will fall back to the default routes (
 import type { RouterConfig } from '@nuxt/schema'
 
 export default {
-  // https://router.vuejs.org/api/interfaces/routeroptions.html#routes
+  // https://router.vuejs.org/api/interfaces/routeroptions#routes
   routes: _routes => [
     {
       name: 'home',
@@ -81,13 +81,13 @@ The [Nuxt kit](/docs/4.x/guide/going-further/kit) provides a few ways [to add ro
 
 ## Router Options
 
-On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions.html), Nuxt offers [additional options](/docs/4.x/api/nuxt-config#router) to customize the router.
+On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions), Nuxt offers [additional options](/docs/4.x/api/nuxt-config#router) to customize the router.
 
 ### Using `router.options`
 
 This is the recommended way to specify [router options](/docs/4.x/api/nuxt-config#router).
 
-```ts [router.options.ts]
+```ts [app/router.options.ts]
 import type { RouterConfig } from '@nuxt/schema'
 
 export default {
@@ -175,7 +175,7 @@ import type { RouterConfig } from '@nuxt/schema'
 import { createMemoryHistory } from 'vue-router'
 
 export default {
-  // https://router.vuejs.org/api/interfaces/routeroptions.html
+  // https://router.vuejs.org/api/interfaces/routeroptions
   history: base => import.meta.client ? createMemoryHistory(base) : null, /* default */
 } satisfies RouterConfig
 ```

package/2.guide/4.recipes/3.custom-usefetch.md

@@ -12,7 +12,7 @@ However, Nuxt provides a way to create a custom fetcher for your API (or multipl
 
 ## Custom `$fetch`
 
-Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/guide/directory-structure/plugins).
+Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/guide/directory-structure/app/plugins).
 
 ::note
 `$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips).

package/2.guide/5.best-practices/hydration.md

@@ -184,5 +184,5 @@ onMounted(() => {
 4. **Avoid side effects in setup**: Move browser-dependent code to `onMounted`
 
 ::tip
-You can read the [Vue documentation on SSR hydration mismatch](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch) for a better understanding of hydration.
+You can read the [Vue documentation on SSR hydration mismatch](https://vuejs.org/guide/scaling-up/ssr#hydration-mismatch) for a better understanding of hydration.
 ::

package/3.api/1.components/10.nuxt-picture.md

@@ -12,7 +12,7 @@ links:
 
 Usage of `<NuxtPicture>` is almost identical to [`<NuxtImg>`](/docs/4.x/api/components/nuxt-img) but it also allows serving modern formats like `webp` when possible.
 
-Learn more about the [`<picture>` tag on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture).
+Learn more about the [`<picture>` tag on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/picture).
 
 ## Setup
 

package/3.api/1.components/11.teleports.md

@@ -4,7 +4,7 @@ description: The <Teleport> component teleports a component to a different locat
 ---
 
 ::warning
-The `to` target of [`<Teleport>`](https://vuejs.org/guide/built-ins/teleport.html) expects a CSS selector string or an actual DOM node. Nuxt currently has SSR support for teleports to `#teleports` only, with client-side support for other targets using a `<ClientOnly>` wrapper.
+The `to` target of [`<Teleport>`](https://vuejs.org/guide/built-ins/teleport) expects a CSS selector string or an actual DOM node. Nuxt currently has SSR support for teleports to `#teleports` only, with client-side support for other targets using a `<ClientOnly>` wrapper.
 ::
 
 ## Body Teleport

package/3.api/1.components/12.nuxt-route-announcer.md

@@ -16,7 +16,7 @@ This component is available in Nuxt v3.12+.
 
 ## Usage
 
-Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
+Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
 
 ```vue [app/app.vue]
 <template>

package/3.api/1.components/2.nuxt-page.md

@@ -11,7 +11,7 @@ links:
 `<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/4.x/guide/directory-structure/app/pages) directory.
 
 ::note
-`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
+`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
 ::
 
 `<NuxtPage>` includes the following components:

package/3.api/1.components/4.nuxt-link.md

@@ -244,21 +244,21 @@ export default defineNuxtConfig({
 
 ### RouterLink
 
-When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/RouterLinkProps.html)
+When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/routerlinkprops)
 
-- `to`: Any URL or a [route location object](https://router.vuejs.org/api/type-aliases/RouteLocation.html) from Vue Router
-- `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-custom)
-- `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exactActiveClass` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-exactActiveClass) on internal links. Defaults to Vue Router's default (`"router-link-exact-active"`)
-- `activeClass`: A class to apply on active links. Works the same as [Vue Router's `activeClass` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-activeClass) on internal links. Defaults to Vue Router's default (`"router-link-active"`)
-- `replace`: Works the same as [Vue Router's `replace` prop](https://router.vuejs.org/api/interfaces/RouteLocationOptions.html#Properties-replace) on internal links
-- `ariaCurrentValue`: An `aria-current` attribute value to apply on exact active links. Works the same as [Vue Router's `ariaCurrentValue` prop](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-ariaCurrentValue) on internal links
+- `to`: Any URL or a [route location object](https://router.vuejs.org/api/type-aliases/routelocation) from Vue Router
+- `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#custom-)
+- `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exactActiveClass` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#exactActiveClass-) on internal links. Defaults to Vue Router's default (`"router-link-exact-active"`)
+- `activeClass`: A class to apply on active links. Works the same as [Vue Router's `activeClass` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#activeClass-) on internal links. Defaults to Vue Router's default (`"router-link-active"`)
+- `replace`: Works the same as [Vue Router's `replace` prop](https://router.vuejs.org/api/interfaces/routelocationoptions#replace-) on internal links
+- `ariaCurrentValue`: An `aria-current` attribute value to apply on exact active links. Works the same as [Vue Router's `ariaCurrentValue` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#ariaCurrentValue-) on internal links
 
 ### NuxtLink
 
 - `href`: An alias for `to`. If used with `to`, `href` will be ignored
 - `noRel`: If set to `true`, no `rel` attribute will be added to the external link
 - `external`: Forces the link to be rendered as an `<a>` tag instead of a Vue Router `RouterLink`.
-- `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/4.x/api/nuxt-config#crossoriginprefetch)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/4.x/api/nuxt-config#crossoriginprefetch) config.
+- `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/4.x/guide/going-further/experimental-features#payloadextraction)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/4.x/guide/going-further/experimental-features#crossoriginprefetch) config.
 - `prefetchOn`: Allows custom control of when to prefetch links. Possible options are `interaction` and `visibility` (default). You can also pass an object for full control, for example: `{ interaction: true, visibility: true }`. This prop is only used when `prefetch` is enabled (default) and `noPrefetch` is not set.
 - `noPrefetch`: Disables prefetching.
 - `prefetchedClass`: A class to apply to links that have been prefetched.
@@ -276,7 +276,7 @@ Defaults can be overwritten, see [overwriting defaults](/docs/4.x/api/components
 
 ### In Nuxt Config
 
-You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/4.x/api/nuxt-config#defaults)
+You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/4.x/guide/going-further/experimental-features#defaults)
 
 ::important
 These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.
@@ -336,8 +336,8 @@ function defineNuxtLink (options: NuxtLinkOptions): Component {}
 
 - `componentName`: A name for the component. Default is `NuxtLink`.
 - `externalRelAttribute`: A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable
-- `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/RouterOptions.html#Properties-linkActiveClass). Defaults to Vue Router's default (`"router-link-active"`)
-- `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/RouterOptions.html#Properties-linkExactActiveClass). Defaults to Vue Router's default (`"router-link-exact-active"`)
+- `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkActiveClass-). Defaults to Vue Router's default (`"router-link-active"`)
+- `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkExactActiveClass-). Defaults to Vue Router's default (`"router-link-exact-active"`)
 - `trailingSlash`: An option to either add or remove trailing slashes in the `href`. If unset or not matching the valid values `append` or `remove`, it will be ignored.
 - `prefetch`: Whether or not to prefetch links by default.
 - `prefetchOn`: Granular control of which prefetch strategies to apply by default.

package/3.api/1.components/5.nuxt-loading-indicator.md

@@ -10,7 +10,7 @@ links:
 
 ## Usage
 
-Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts).
+Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/guide/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/guide/directory-structure/app/layouts).
 
 ```vue [app/app.vue]
 <template>

package/3.api/1.components/6.nuxt-error-boundary.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::tip
-The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured) hook under the hood.
+The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured) hook under the hood.
 ::
 
 ## Events

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

@@ -16,4 +16,4 @@ const appConfig = useAppConfig()
 console.log(appConfig)
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app-config"}
+:read-more{to="/docs/4.x/guide/directory-structure/app/app-config"}

package/3.api/2.composables/use-async-data.md

@@ -18,9 +18,9 @@ Within your pages, components, and plugins you can use useAsyncData to get acces
 
 ```vue [app/pages/index.vue]
 <script setup lang="ts">
-const { data, status, error, refresh, clear } = await useAsyncData(
+const { data, status, pending, error, refresh, clear } = await useAsyncData(
   'mountains',
-  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
 )
 </script>
 ```
@@ -30,7 +30,7 @@ If you're using a custom useAsyncData wrapper, do not await it in the composable
 ::
 
 ::note
-`data`, `status` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
+`data`, `status`, `pending` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
 ::
 
 ### Watch Params
@@ -42,10 +42,11 @@ The built-in `watch` option allows automatically rerunning the fetcher function
 const page = ref(1)
 const { data: posts } = await useAsyncData(
   'posts',
-  () => $fetch('https://fakeApi.com/posts', {
+  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
     params: {
       page: page.value,
     },
+    signal,
   }), {
     watch: [page],
   },
@@ -70,6 +71,64 @@ const { data: user } = useAsyncData(
 </script>
 ```
 
+### Make your `handler` abortable
+
+You can make your `handler` function abortable by using the `signal` provided in the second argument. This is useful for cancelling requests when they are no longer needed, such as when a user navigates away from a page. `$fetch` natively supports abort signals.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh()
+
+clear() // will cancel the latest pending handler
+```
+
+You can also pass an `AbortSignal` to the `refresh`/`execute` function to cancel individual requests manually.
+
+```ts
+const { refresh } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+let abortController: AbortController | undefined
+
+function handleUserAction () {
+  abortController = new AbortController()
+  refresh({ signal: abortController.signal })
+}
+
+function handleCancel () {
+  abortController?.abort() // aborts the ongoing refresh request
+}
+```
+
+If your `handler` function does not support abort signals, you can implement your own abort logic using the `signal` provided.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => {
+    return new Promise((resolve, reject) => {
+      signal?.addEventListener('abort', () => {
+        reject(new Error('Request aborted'))
+      })
+      return Promise.resolve(callback.call(this, yourHandler)).then(resolve, reject)
+    })
+  },
+)
+```
+
+The handler signal will be aborted when:
+
+- A new request is made with `dedupe: 'cancel'`
+- The `clear` function is called
+- The `options.timeout` duration is exceeded
+
 ::warning
 [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
 ::
@@ -116,7 +175,7 @@ You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `u
 
 ### Shared State and Option Consistency
 
-When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires option consistency.
+When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error`, `status` and `pending` refs. This ensures consistency across components but requires option consistency.
 
 The following options **must be consistent** across all calls with the same key:
 - `handler` function
@@ -135,12 +194,12 @@ The following options **can differ** without triggering warnings:
 
 ```ts
 // ❌ This will trigger a development warning
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })
 
 // ✅ This is allowed
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
 ```
 
 ::tip
@@ -159,6 +218,7 @@ Keyed state created using `useAsyncData` can be retrieved across your Nuxt appli
   - `pending`: the request is in progress
   - `success`: the request has completed successfully
   - `error`: the request has failed
+- `pending`: a `Ref<boolean>` that is `true` while the request is in progress (that is, while `status.value === 'pending'`).
 - `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
@@ -170,14 +230,16 @@ If you have not fetched data on the server (for example, with `server: false`),
 ## Type
 
 ```ts [Signature]
+export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<ResT>
+
 export function useAsyncData<DataT, DataE> (
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
-  options?: AsyncDataOptions<DataT>
+  handler: AsyncDataHandler<DataT>,
+  options?: AsyncDataOptions<DataT>,
 ): AsyncData<DataT, DataE>
 export function useAsyncData<DataT, DataE> (
   key: MaybeRefOrGetter<string>,
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
-  options?: AsyncDataOptions<DataT>
+  handler: AsyncDataHandler<DataT>,
+  options?: AsyncDataOptions<DataT>,
 ): Promise<AsyncData<DataT, DataE>>
 
 type AsyncDataOptions<DataT> = {
@@ -206,6 +268,7 @@ type AsyncData<DataT, ErrorT> = {
   clear: () => void
   error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
+  pending: Ref<boolean>
 }
 
 interface AsyncDataExecuteOptions {

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

@@ -42,7 +42,7 @@ export interface CookieRef<T> extends Ref<T> {}
 
 export function useCookie<T = string | null | undefined> (
   name: string,
-  options?: CookieOptions<T>
+  options?: CookieOptions<T>,
 ): CookieRef<T>
 ```
 
@@ -61,14 +61,14 @@ Most of the options will be directly passed to the [cookie](https://github.com/j
 | `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. |
+| `maxAge` | `number` | `undefined` | Max age in seconds for the cookie, i.e. the value for the [`Max-Age` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/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://datatracker.ietf.org/doc/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. |
+| `secure` | `boolean` | `false` | Sets the [`Secure` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/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. |
+| `domain` | `string` | `undefined` | Sets the [`Domain` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/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://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4). By default, the path is considered the ["default path"](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4). |
+| `sameSite` | `boolean \| string` | `undefined` | Sets the [`SameSite` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/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