@nuxt/docs-nightly 4.3.0-29356103.2f7957ac → 4.3.0-29430576.f48ea4c8

package/3.guide/4.modules/6.best-practices.md

@@ -0,0 +1,104 @@
+---
+title: "Follow Best Practices"
+description: "Build performant and maintainable Nuxt modules with these guidelines."
+---
+
+With great power comes great responsibility. While modules are powerful, here are some best practices to keep in mind while authoring modules to keep applications performant and developer experience great.
+
+## Handle Async Setup
+
+As we've seen, Nuxt modules can be asynchronous. For example, you may want to develop a module that needs fetching some API or calling an async function.
+
+However, be careful with asynchronous behaviors as Nuxt will wait for your module to setup before going to the next module and starting the development server, build process, etc. Prefer deferring time-consuming logic to Nuxt hooks.
+
+::warning
+If your module takes more than **1 second** to setup, Nuxt will emit a warning about it.
+::
+
+## Prefix Your Exports
+
+Nuxt modules should provide an explicit prefix for any exposed configuration, plugin, API, composable, component, or server route to avoid conflicts with other modules, Nuxt internals, or user-defined code.
+
+Ideally, prefix them with your module's name. For example, if your module is called `nuxt-foo`:
+
+| Type | ❌ Avoid | ✅ Prefer |
+| --- | --- | --- |
+| Components | `<Button>`, `<Modal>` | `<FooButton>`, `<FooModal>` |
+| Composables | `useData()`, `useModal()` | `useFooData()`, `useFooModal()` |
+| Server routes | `/api/track`, `/api/data` | `/api/_foo/track`, `/api/_foo/data` |
+
+### Server Routes
+
+This is particularly important for server routes, where common paths like `/api/auth`, `/api/login`, or `/api/user` are very likely already used by the application.
+
+Use a unique prefix based on your module name:
+- `/api/_foo/...` (using underscore prefix)
+- `/_foo/...` (for non-API routes)
+
+## Use Lifecycle Hooks
+
+When your module needs to perform one-time setup tasks (like generating configuration files, setting up databases, or installing dependencies), use lifecycle hooks instead of running the logic in your main `setup` function.
+
+```ts
+import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
+import semver from 'semver'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-database-module',
+    version: '1.0.0',
+  },
+  async onInstall (nuxt) {
+    // One-time setup: create database schema, generate config files, etc.
+    await generateDatabaseConfig(nuxt.options.rootDir)
+  },
+  async onUpgrade (options, nuxt, previousVersion) {
+    // Handle version-specific migrations
+    if (semver.lt(previousVersion, '1.0.0')) {
+      await migrateLegacyData()
+    }
+  },
+  setup (options, nuxt) {
+    // Regular setup logic that runs on every build
+    addServerHandler({ /* ... */ })
+  },
+})
+```
+
+This pattern prevents unnecessary work on every build and provides a better developer experience. See the [lifecycle hooks documentation](/docs/4.x/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) for more details.
+
+## Be TypeScript Friendly
+
+Nuxt has first-class TypeScript integration for the best developer experience.
+
+Exposing types and using TypeScript to develop modules benefits users even when not using TypeScript directly.
+
+## Use ESM Syntax
+
+Nuxt relies on native ESM. Please read [Native ES Modules](/docs/4.x/guide/concepts/esm) for more information.
+
+## Document Your Module
+
+Consider documenting module usage in the readme file:
+
+- Why use this module?
+- How to use this module?
+- What does this module do?
+
+Linking to the integration website and documentation is always a good idea.
+
+## Provide a Demo
+
+It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v4) that you add to your module readme.
+
+This not only provides potential users of your module a quick and easy way to experiment with the module but also an easy way for them to build minimal reproductions they can send you when they encounter issues.
+
+## Stay Version Agnostic
+
+Nuxt, Nuxt Kit, and other new toolings are made to have both forward and backward compatibility in mind.
+
+Please use "X for Nuxt" instead of "X for Nuxt 3" to avoid fragmentation in the ecosystem and prefer using `meta.compatibility` to set Nuxt version constraints.
+
+## Follow Starter Conventions
+
+The module starter comes with a default set of tools and configurations (e.g. ESLint configuration). If you plan on open-sourcing your module, sticking with those defaults ensures your module shares a consistent coding style with other [community modules](/modules) out there, making it easier for others to contribute.

package/3.guide/4.modules/7.ecosystem.md

@@ -0,0 +1,32 @@
+---
+title: "Publish & Share Your Module"
+description: "Join the Nuxt module ecosystem and publish your module to npm."
+---
+
+The [Nuxt module ecosystem](/modules) represents more than 35 million monthly NPM downloads and provides extended functionalities and integrations with all sort of tools. You can be part of this ecosystem!
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/exploring-nuxt-modules-ecosystem-and-module-types?friend=nuxt" target="_blank"}
+Watch Vue School video about Nuxt module types.
+::
+
+## Understand Module Types
+
+**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.
+
+**Third-party and other community modules** are modules (often) prefixed with `nuxt-`. Anyone can make them, using this prefix allows these modules to be discoverable on npm. This is the best starting point to draft and try an idea!
+
+**Private or personal modules** are modules made for your own use case or company. They don't need to follow any naming rules to work with Nuxt and are often seen scoped under an npm organization (e.g. `@my-company/nuxt-auth`)
+
+## List Your Module
+
+Any community modules are welcome to be listed on [the module list](/modules). To be listed, [open an issue in the nuxt/modules](https://github.com/nuxt/modules/issues/new?template=module_request.yml) repository. The Nuxt team can help you to apply best practices before listing.
+
+## Join nuxt-modules
+
+By moving your modules to [nuxt-modules](https://github.com/nuxt-modules), there is always someone else to help, and this way, we can join forces to make one perfect solution.
+
+If you have an already published and working module, and want to transfer it to `nuxt-modules`, [open an issue in nuxt/modules](https://github.com/nuxt/modules/issues/new).
+
+By joining `nuxt-modules` we can rename your community module under the `@nuxtjs/` scope and provide a subdomain (e.g. `my-module.nuxtjs.org`) for its documentation.

package/3.guide/4.modules/index.md

@@ -0,0 +1,36 @@
+---
+title: 'Module Author Guide'
+titleTemplate: '%s'
+description: 'Learn how to create a Nuxt module to integrate, enhance or extend any Nuxt applications.'
+navigation: false
+surround: false
+---
+
+Nuxt's [configuration](/docs/4.x/api/nuxt-config) and [hooks](/docs/4.x/guide/going-further/hooks) systems make it possible to customize every aspect of Nuxt and add any integration you might need (Vue plugins, CMS, server routes, components, logging, etc.).
+
+**Nuxt modules** are functions that sequentially run when starting Nuxt in development mode using `nuxt dev` or building a project for production with `nuxt build`.
+With modules, you can encapsulate, properly test, and share custom solutions as npm packages without adding unnecessary boilerplate to your project, or requiring changes to Nuxt itself.
+
+::card-group{class="sm:grid-cols-1"}
+  ::card{icon="i-lucide-rocket" title="Create Your First Module" to="/docs/4.x/guide/modules/getting-started"}
+  Learn how to create your first Nuxt module using the official starter template.
+  ::
+  ::card{icon="i-lucide-box" title="Understand Module Structure" to="/docs/4.x/guide/modules/module-anatomy"}
+  Learn how Nuxt modules are structured and how to define them.
+  ::
+  ::card{icon="i-lucide-code" title="Add Plugins, Components & More" to="/docs/4.x/guide/modules/recipes-basics"}
+  Learn how to inject plugins, components, composables and server routes from your module.
+  ::
+  ::card{icon="i-lucide-layers" title="Use Hooks & Extend Types" to="/docs/4.x/guide/modules/recipes-advanced"}
+  Master lifecycle hooks, virtual files and TypeScript declarations in your modules.
+  ::
+  ::card{icon="i-lucide-test-tube" title="Test Your Module" to="/docs/4.x/guide/modules/testing"}
+  Learn how to test your Nuxt module with unit, integration and E2E tests.
+  ::
+  ::card{icon="i-lucide-medal" title="Follow Best Practices" to="/docs/4.x/guide/modules/best-practices"}
+  Build performant and maintainable Nuxt modules with these guidelines.
+  ::
+  ::card{icon="i-lucide-globe" title="Publish & Share Your Module" to="/docs/4.x/guide/modules/ecosystem"}
+  Join the Nuxt module ecosystem and publish your module to npm.
+  ::
+::

package/{2.guide/4.recipes → 3.guide/5.recipes}/1.custom-routing.md

@@ -5,7 +5,7 @@ description: "In Nuxt, your routing is defined by the structure of your files in
 
 ## Adding custom routes
 
-In Nuxt, your routing is defined by the structure of your files inside the [app/pages directory](/docs/4.x/guide/directory-structure/app/pages). However, since it uses [vue-router](https://router.vuejs.org) under the hood, Nuxt offers you several ways to add custom routes in your project.
+In Nuxt, your routing is defined by the structure of your files inside the [app/pages directory](/docs/4.x/directory-structure/app/pages). However, since it uses [vue-router](https://router.vuejs.org) under the hood, Nuxt offers you several ways to add custom routes in your project.
 
 ### Router Config
 
@@ -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.guide/5.recipes}/2.vite-plugin.md

@@ -28,7 +28,7 @@ First, we need to install the Vite plugin, for our example, we'll use `@rollup/p
 
 ::
 
-Next, we need to import and add it to our [`nuxt.config.ts`](/docs/4.x/guide/directory-structure/nuxt-config) file:
+Next, we need to import and add it to our [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file:
 
 ```ts [nuxt.config.ts]
 import yaml from '@rollup/plugin-yaml'

package/{2.guide/4.recipes → 3.guide/5.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/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/4.recipes → 3.guide/5.recipes}/4.sessions-and-authentication.md

@@ -155,7 +155,7 @@ export default defineEventHandler(async (event) => {
 
 ## Protect App Routes
 
-Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](https://nuxt.com/docs/4.x/guide/directory-structure/app/middleware) to protect the route on the client side and redirect users to the login page.
+Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](https://nuxt.com/docs/4.x/directory-structure/app/middleware) to protect the route on the client side and redirect users to the login page.
 
 `nuxt-auth-utils` provides a convenient `useUserSession` composable which we'll use to check if the user is logged in, and redirect them if they are not.
 

package/{2.guide/3.going-further → 3.guide/6.going-further}/1.events.md

@@ -1,10 +1,9 @@
 ---
-title: "Events"
+title: "Creating Custom Events"
 description: "Nuxt provides a powerful event system powered by hookable."
+navigation.title: "Custom Events"
 ---
 
-# Events
-
 Using events is a great way to decouple your application and allow for more flexible and modular communication between different parts of your code. Events can have multiple listeners that do not depend on each other. For example, you may wish to send an email to your user each time an order has shipped. Instead of coupling your order processing code to your email code, you can emit an event which a listener can receive and use to dispatch an email.
 
 The Nuxt event system is powered by [unjs/hookable](https://github.com/unjs/hookable), which is the same library that powers the Nuxt hooks system.

package/{2.guide/3.going-further → 3.guide/6.going-further}/1.experimental-features.md

@@ -5,7 +5,7 @@ description: "Enable Nuxt experimental features to unlock new possibilities."
 
 Nuxt includes experimental features that you can enable in your configuration file.
 
-Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
+Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/guide/going-further/experimental-features) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
 
 ::note
 Note that these features are experimental and could be removed or modified in the future.
@@ -131,7 +131,7 @@ Emits `app:chunkError` hook when there is an error loading vite/webpack chunks.
 
 By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).
 
-Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/guide/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
+Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
 
 You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
 
@@ -290,7 +290,7 @@ export default defineNuxtConfig({
 
 :link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
 
-::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API" target="_blank"}
+::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API" target="_blank"}
 Read more about the **View Transition API**.
 ::
 
@@ -318,7 +318,7 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/4.x/guide/directory-structure/app/components#server-components"}
+:read-more{to="/docs/4.x/directory-structure/app/components#server-components"}
 
 ::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
 You can follow the server components roadmap on GitHub.
@@ -405,12 +405,12 @@ should do this automatically for you.)
 // This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
 // to the data fetched, but Nuxt can't know that because it's not reflected in the key.
 const route = useRoute()
-const { data } = await useAsyncData(async () => {
-  return await $fetch(`/api/my-page/${route.params.slug}`)
+const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
+  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
 })
 // Instead, you should use a key that uniquely identifies the data fetched.
-const { data } = await useAsyncData(route.params.slug, async () => {
-  return await $fetch(`/api/my-page/${route.params.slug}`)
+const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
+  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
 })
 ```
 
@@ -541,7 +541,7 @@ export default defineNuxtConfig({
 })
 ```
 
-This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/guide/directory-structure/app/pages#typing-custom-metadata).
+This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/directory-structure/app/pages#typing-custom-metadata).
 
 ## navigationRepaint
 
@@ -665,7 +665,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{icon="i-simple-icons-github" color="gray" to="/docs/4.x/guide/directory-structure/app/components#delayed-or-lazy-hydration"}
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration"}
 Read more about lazy hydration.
 ::
 

package/{2.guide/3.going-further → 3.guide/6.going-further}/1.features.md

@@ -91,7 +91,7 @@ export default defineNuxtConfig({
 
 ### typescriptBundlerResolution
 
-This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance.html#reduce-resolve-operations).
+This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance#reduce-resolve-operations).
 
 It improves type support when using modern libraries with `exports`.
 

package/{2.guide/3.going-further → 3.guide/6.going-further}/1.internals.md

@@ -1,6 +1,7 @@
 ---
 title: "How Nuxt Works?"
 description: "Nuxt is a minimal but highly customizable framework to build web applications."
+navigation: false
 ---
 
 This guide helps you better understand Nuxt internals to develop new solutions and module integrations on top of Nuxt.
@@ -15,7 +16,7 @@ allowing different components to communicate with each other. You can think of i
 This context is globally available to be used with [Nuxt Kit](/docs/4.x/guide/going-further/kit) composables.
 Therefore only one instance of Nuxt is allowed to run per process.
 
-To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/4.x/guide/going-further/modules).
+To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt modules](/docs/4.x/guide/modules).
 
 For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nuxt.ts).
 
@@ -30,7 +31,7 @@ Global usage is possible for the browser but not on the server, to avoid sharing
 
 Since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.
 
-To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/guide/directory-structure/plugins).
+To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins).
 
 Check [Nuxt App](/docs/4.x/api/composables/use-nuxt-app) for more information about this interface.
 
@@ -76,6 +77,6 @@ Nuxt builds and bundles project using Node.js but also has a runtime side.
 
 While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
 
-`nuxt.config` and [Nuxt Modules](/docs/4.x/guide/going-further/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/guide/directory-structure/plugins) can be used to extend runtime.
+`nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) can be used to extend runtime.
 
-When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/4.x/guide/going-further/modules).
+When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules).

package/{2.guide/3.going-further → 3.guide/6.going-further}/10.runtime-config.md

@@ -5,7 +5,7 @@ description: "Nuxt provides a runtime config API to expose configuration and sec
 
 ## Exposing
 
-To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/4.x/guide/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) option.
+To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) option.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -45,7 +45,7 @@ The most common way to provide configuration is by using [Environment Variables]
 
 ::note
 The Nuxt CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.
-:read-more{to="/docs/4.x/guide/directory-structure/env"}
+:read-more{to="/docs/4.x/directory-structure/env"}
 ::
 
 Runtime config values are **automatically replaced by matching environment variables at runtime**.

package/{2.guide/3.going-further → 3.guide/6.going-further}/2.hooks.md

@@ -9,7 +9,7 @@ The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookabl
 
 ## Nuxt Hooks (Build Time)
 
-These hooks are available for [Nuxt Modules](/docs/4.x/guide/going-further/modules) and build context.
+These hooks are available for [Nuxt modules](/docs/4.x/guide/modules) and build context.
 
 ### Within `nuxt.config.ts`
 
@@ -39,7 +39,7 @@ Explore all available Nuxt hooks.
 
 ## App Hooks (Runtime)
 
-App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/guide/directory-structure/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
+App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
 
 ```ts [app/plugins/test.ts]
 export default defineNuxtPlugin((nuxtApp) => {
@@ -55,7 +55,7 @@ Explore all available App hooks.
 
 ## Server Hooks (Runtime)
 
-These hooks are available for [server plugins](/docs/4.x/guide/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
+These hooks are available for [server plugins](/docs/4.x/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
 
 ```ts [~/server/plugins/test.ts]
 export default defineNitroPlugin((nitroApp) => {

package/{2.guide/3.going-further → 3.guide/6.going-further}/4.kit.md

@@ -3,7 +3,7 @@ title: "Nuxt Kit"
 description: "@nuxt/kit provides features for module authors."
 ---
 
-Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt Modules](/docs/4.x/guide/going-further/modules) super easy.
+Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt modules](/docs/4.x/guide/modules) super easy.
 
 ::read-more{to="/docs/4.x/api/kit"}
 Discover all Nuxt Kit utilities.

package/{2.guide/3.going-further → 3.guide/6.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/directory-structure/app/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/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/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/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 → 3.guide/6.going-further}/7.layers.md

@@ -7,7 +7,7 @@ Nuxt layers are a powerful feature that you can use to share and reuse partial N
 
 :read-more{to="/docs/4.x/getting-started/layers"}
 
-A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/4.x/guide/directory-structure/nuxt-config) file to indicate it is a layer.
+A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file to indicate it is a layer.
 
 ```ts [base/nuxt.config.ts]
 export default defineNuxtConfig({})
@@ -15,20 +15,20 @@ export default defineNuxtConfig({})
 
 Additionally, certain other files in the layer directory will be auto-scanned and used by Nuxt for the project extending this layer.
 
-- [`app/components/*`](/docs/4.x/guide/directory-structure/app/components)   - Extend the default components
-- [`app/composables/*`](/docs/4.x/guide/directory-structure/app/composables)  - Extend the default composables
-- [`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/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
-- [`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
+- [`app/components/*`](/docs/4.x/directory-structure/app/components)   - Extend the default components
+- [`app/composables/*`](/docs/4.x/directory-structure/app/composables)  - Extend the default composables
+- [`app/layouts/*`](/docs/4.x/directory-structure/app/layouts)  - Extend the default layouts
+- [`app/middleware/*`](/docs/4.x/directory-structure/app/middleware)  - Extend the default middleware
+- [`app/pages/*`](/docs/4.x/directory-structure/app/pages)        - Extend the default pages
+- [`app/plugins/*`](/docs/4.x/directory-structure/app/plugins)        - Extend the default plugins
+- [`app/utils/*`](/docs/4.x/directory-structure/app/utils)   - Extend the default utils
+- [`app/app.config.ts`](/docs/4.x/directory-structure/app/app-config)  - Extend the default app config
+- [`server/*`](/docs/4.x/directory-structure/server)       - Extend the default server endpoints & middleware
+- [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config)- Extend the default nuxt config
 
 ## Basic Example
 
-::code-group
+::code-tree{defaultValue="nuxt.config.ts" expandAll}
 
   ```ts [nuxt.config.ts]
   export default defineNuxtConfig({
@@ -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 → 3.guide/6.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/{3.api → 4.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 → 4.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