@nuxt/docs 3.20.2 → 3.21.1

package/1.getting-started/18.upgrade.md

@@ -6,6 +6,35 @@ navigation.icon: i-lucide-circle-arrow-up
 
 ## Upgrading Nuxt
 
+### Latest Nuxt 3 release
+
+To upgrade Nuxt to the [latest v3 release](https://github.com/nuxt/nuxt/releases), use the `nuxt upgrade` command with `--channel=v3` flag.
+
+::code-group{sync="pm"}
+
+```bash [npm]
+npx nuxt upgrade --dedupe --channel=v3
+```
+
+```bash [yarn]
+yarn nuxt upgrade --dedupe --channel=v3
+```
+
+```bash [pnpm]
+pnpm nuxt upgrade --dedupe --channel=v3
+```
+
+```bash [bun]
+bun x nuxt upgrade --dedupe --channel=v3
+```
+
+::
+
+::note
+This will only work if you _already have_ a version of `@nuxt/cli` which has the `--channel` flag implemented. If this does not work, you can instead use `nuxi@latest` for the initial upgrade.
+E.g. `npx nuxi@latest upgrade --dedupe --channel=v3`
+::
+
 ### Latest release
 
 To upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases), use the `nuxt upgrade` command.
@@ -28,6 +57,10 @@ pnpm nuxt upgrade
 bun x nuxt upgrade
 ```
 
+```bash [deno]
+deno x nuxt upgrade
+```
+
 ::
 
 ### Nightly Release Channel
@@ -99,46 +132,47 @@ For now, you need to define the compatibility version in each layer that opts in
 
 When you set your `compatibilityVersion` to `4`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v4 behavior, but you can granularly re-enable Nuxt v3 behavior when testing, following the commented out lines above. Please file issues if so, so that we can address them in Nuxt or in the ecosystem.
 
-Breaking or significant changes will be noted here along with migration steps for backward/forward compatibility.
-
-::note
-This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 4 using `compatibilityVersion: 4`.
-::
+Breaking or significant changes are documented below along with migration steps and available configuration options.
 
 ### Migrating Using Codemods
 
-To facilitate the upgrade process, we have collaborated with the [Codemod](https://github.com/codemod-com/codemod) team to automate many migration steps with some open-source codemods.
+To facilitate the upgrade process, we have collaborated with the [Codemod](https://github.com/codemod/codemod) team to automate many migration steps with some open-source codemods.
 
 ::note
 If you encounter any issues, please report them to the Codemod team with `npx codemod feedback` 🙏
 ::
 
-For a complete list of Nuxt 4 codemods, detailed information on each, their source, and various ways to run them, visit the [Codemod Registry](https://go.codemod.com/codemod-registry).
+For a complete list of Nuxt 4 codemods, detailed information on each, their source, and various ways to run them, visit the [Codemod Registry](https://app.codemod.com/registry).
 
 You can run all the codemods mentioned in this guide using the following `codemod` recipe:
 
 ::code-group
 
 ```bash [npm]
-# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+# Using pinned version due to https://github.com/codemod/codemod/issues/1710
 npx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [yarn]
-# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+# Using pinned version due to https://github.com/codemod/codemod/issues/1710
 yarn dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [pnpm]
-# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+# Using pinned version due to https://github.com/codemod/codemod/issues/1710
 pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [bun]
-# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+# Using pinned version due to https://github.com/codemod/codemod/issues/1710
 bun x codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
+```bash [deno]
+# Using pinned version due to https://github.com/codemod/codemod/issues/1710
+deno x codemod@0.18.7 nuxt/4/migration-recipe
+```
+
 ::
 
 This command will execute all codemods in sequence, with the option to deselect any that you do not wish to run. Each codemod is also listed below alongside its respective change and can be executed independently.
@@ -153,11 +187,11 @@ Nuxt now defaults to a new directory structure, with backwards compatibility (so
 
 #### What Changed
 
-* the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
-* `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
-* `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
-* if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
-* a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
+- the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
+- `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
+- `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
+- if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
+- a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
 
 <details>
 
@@ -193,6 +227,10 @@ server/
 nuxt.config.ts
 ```
 
+::note
+With this new structure, the `~` alias now points to the `app/` directory by default (your `srcDir`). This means `~/components` resolves to `components/`, `~/pages` to `pages/`, etc.
+::
+
 </details>
 
 👉 For more details, see the [PR implementing this change](https://github.com/nuxt/nuxt/pull/27029).
@@ -318,15 +356,15 @@ Now modules are loaded in the correct order:
 2. **Project modules last** (highest priority)
 
 This affects both:
-* Modules defined in the `modules` array in `nuxt.config.ts`
-* Auto-discovered modules from the `modules/` directory
+- Modules defined in the `modules` array in `nuxt.config.ts`
+- Auto-discovered modules from the `modules/` directory
 
 #### Reasons for Change
 
 This change ensures that:
-* Extended layers have lower priority than the consuming project
-* Module execution order matches the intuitive layer inheritance pattern
-* Module configuration and hooks work as expected in multi-layer setups
+- Extended layers have lower priority than the consuming project
+- Module execution order matches the intuitive layer inheritance pattern
+- Module configuration and hooks work as expected in multi-layer setups
 
 #### Migration Steps
 
@@ -358,7 +396,7 @@ export default defineNuxtConfig({
 // 4. project-module-2 (can override layer modules)
 ```
 
-If you encounter issues with module order dependencies due to needing to register a hook, consider using the [`modules:done` hook](/docs/3.x/guide/going-further/modules#custom-hooks) for modules that need to call a hook. This is run after all other modules have been loaded, which means it is safe to use.
+If you encounter issues with module order dependencies due to needing to register a hook, consider using the [`modules:done` hook](/docs/3.x/guide/modules#custom-hooks) for modules that need to call a hook. This is run after all other modules have been loaded, which means it is safe to use.
 
 👉 See [PR #31507](https://github.com/nuxt/nuxt/pull/31507) and [issue #25719](https://github.com/nuxt/nuxt/issues/25719) for more details.
 
@@ -433,9 +471,9 @@ export default defineNuxtConfig({
 [Unhead](https://unhead.unjs.io/), used to generate `<head>` tags, has been updated to version 2. While mostly compatible it includes several breaking changes
 for lower-level APIs.
 
-* Removed props: `vmid`, `hid`, `children`, `body`.
-* Promise input no longer supported.
-* Tags are now sorted using Capo.js by default.
+- Removed props: `vmid`, `hid`, `children`, `body`.
+- Promise input no longer supported.
+- Tags are now sorted using Capo.js by default.
 
 #### Migration Steps
 
@@ -443,7 +481,7 @@ The above changes should have minimal impact on your app.
 
 If you have issues you should verify:
 
-* You're not using any of the removed props.
+- You're not using any of the removed props.
 
 ```diff
 useHead({
@@ -456,7 +494,7 @@ useHead({
 })
 ```
 
-* If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
+- If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
 
 ```ts
 import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'
@@ -493,7 +531,7 @@ export default defineNuxtConfig({
 
 #### What Changed
 
-When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `app/spa-loading-template.html`), within the Nuxt app root:
+When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/app/spa-loading-template.html` - note that this has also changed to `~/spa-loading-template.html` in Nuxt 4), within the Nuxt app root:
 
 ```html
 <div id="__nuxt">
@@ -638,7 +676,7 @@ For example, if your site requires a `useFetch` call for every page (for example
 
 Make sure that any unique key of your data is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch` should do this automatically for you.)
 
-```ts [app/pages/test/[slug\\].vue]
+```ts [pages/test/[slug\\].vue]
 // 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()
@@ -989,15 +1027,15 @@ In Nuxt v3 we moved to a 'virtual' syntax with a `getContents()` function which
 
 In addition, `lodash/template` has had a succession of security issues. These do not really apply to Nuxt projects because it is being used at build-time, not runtime, and by trusted code. However, they still appear in security audits. Moreover, `lodash` is a hefty dependency and is unused by most projects.
 
-Finally, providing code serialization functions directly within Nuxt is not ideal. Instead, we maintain projects like [unjs/knitwork](http://github.com/unjs/knitwork) which can be dependencies of your project, and where security issues can be reported/resolved directly without requiring an upgrade of Nuxt itself.
+Finally, providing code serialization functions directly within Nuxt is not ideal. Instead, we maintain projects like [unjs/knitwork](https://github.com/unjs/knitwork) which can be dependencies of your project, and where security issues can be reported/resolved directly without requiring an upgrade of Nuxt itself.
 
 #### Migration Steps
 
 We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:
 
-* Moving your string interpolation logic directly into `getContents()`.
-* Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
-* Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
+- Moving your string interpolation logic directly into `getContents()`.
+- Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
+- Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
 
 ```diff
 + import { readFileSync } from 'node:fs'
@@ -1080,11 +1118,11 @@ There are two approaches:
 Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:
 
 1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
-   * `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
-   * `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
-   * `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
-   * `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
-   * `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
+   - `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
+   - `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
+   - `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
+   - `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
+   - `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
 
 2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
 
@@ -1113,8 +1151,13 @@ However, to take advantage of improved type checking, you can opt in to the new
 
 1. **Update your root `tsconfig.json`** to use project references:
 
+   ::note
+   If your `tsconfig.json` currently has an `"extends": "./.nuxt/tsconfig.json"` line, **remove it** before adding the references. Project references and extends are mutually exclusive.
+   ::
+
    ```json
    {
+     // Remove "extends": "./.nuxt/tsconfig.json" if present
      "files": [],
      "references": [
        { "path": "./.nuxt/tsconfig.app.json" },
@@ -1135,30 +1178,38 @@ However, to take advantage of improved type checking, you can opt in to the new
    ```
 
 4. **Move all type augmentations into their appropriate context**:
-   * If you are augmenting types for the app context, move the files to the `app/` directory.
-   * If you are augmenting types for the server context, move the files to the `server/` directory.
-   * If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
+   - If you are augmenting types for the app context, move the files to the `app/` directory.
+   - If you are augmenting types for the server context, move the files to the `server/` directory.
+   - If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.
 
     ::warning
     Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.
     ::
 
-5. **Configure Node.js TypeScript options** if needed:
+5. **Configure TypeScript options** if needed:
    <!-- @case-police-ignore tsConfig -->
 
    ```ts
    export default defineNuxtConfig({
      typescript: {
-       // Customize app/server TypeScript config
+       // customize tsconfig.app.json
        tsConfig: {
-         compilerOptions: {
-           strict: true,
-         },
+         // ...
        },
-       // Customize build-time TypeScript config
+       // customize tsconfig.shared.json
+       sharedTsConfig: {
+         // ...
+       },
+       // customize tsconfig.node.json
        nodeTsConfig: {
-         compilerOptions: {
-           strict: true,
+         // ...
+       },
+     },
+     nitro: {
+       typescript: {
+         // customize tsconfig.server.json
+         tsConfig: {
+           // ...
          },
        },
      },
@@ -1177,11 +1228,11 @@ The new configuration provides better type safety and IntelliSense for projects
 
 Four experimental features are no longer configurable in Nuxt 4:
 
-* `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
-* `experimental.configSchema` will be `true` (default since v3.3)
-* `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
-* `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
-* `vite.devBundler` is no longer configurable - it will use `vite-node` by default
+- `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
+- `experimental.configSchema` will be `true` (default since v3.3)
+- `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
+- `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
+- `vite.devBundler` is no longer configurable - it will use `vite-node` by default
 
 #### Reasons for Change
 
@@ -1189,9 +1240,9 @@ These options have been set to their current values for some time and we do not
 
 #### Migration Steps
 
-* `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
+- `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
 
-* `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
+- `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
 
 ### Removal of Top-Level `generate` Configuration
 
@@ -1201,8 +1252,8 @@ These options have been set to their current values for some time and we do not
 
 The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:
 
-* `generate.exclude` - for excluding routes from prerendering
-* `generate.routes` - for specifying routes to prerender
+- `generate.exclude` - for excluding routes from prerendering
+- `generate.routes` - for specifying routes to prerender
 
 #### Reasons for Change
 
@@ -1257,7 +1308,7 @@ Static sites             | ✅             | ✅                | ✅
 
 The migration guide provides a step-by-step comparison of Nuxt 2 features to Nuxt 3+ features and guidance to adapt your current application.
 
-::read-more{to="/docs/migration/overview"}
+::read-more{to="/docs/3.x/migration/overview"}
 Check out the **guide to migrating from Nuxt 2 to Nuxt 3**.
 ::
 
@@ -1265,6 +1316,6 @@ Check out the **guide to migrating from Nuxt 2 to Nuxt 3**.
 
 If you prefer to progressively migrate your Nuxt 2 application to Nuxt 3, you can use Nuxt Bridge. Nuxt Bridge is a compatibility layer that allows you to use Nuxt 3+ features in Nuxt 2 with an opt-in mechanism.
 
-::read-more{to="/docs/bridge/overview"}
+::read-more{to="/docs/3.x/bridge/overview"}
 **Migrate from Nuxt 2 to Nuxt Bridge**
 ::

package/2.directory-structure/0.output.md

@@ -11,7 +11,7 @@ This directory should be added to your [`.gitignore`](/docs/3.x/directory-struct
 
 Use this directory to deploy your Nuxt application to production.
 
-:read-more{to="/docs/getting-started/deployment"}
+:read-more{to="/docs/3.x/getting-started/deployment"}
 
 ::warning
 You should not touch any files inside since the whole directory will be re-created when running [`nuxt build`](/docs/3.x/api/commands/build).

package/2.directory-structure/1.assets.md

@@ -13,4 +13,4 @@ The directory usually contains the following types of files:
 
 If you want to serve assets from the server, we recommend taking a look at the [`public/`](/docs/3.x/directory-structure/public) directory.
 
-:read-more{to="/docs/getting-started/assets"}
+:read-more{to="/docs/3.x/getting-started/assets"}

package/2.directory-structure/1.components.md

@@ -163,7 +163,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).
 ::
 
 #### `hydrate-on-idle`
@@ -181,7 +181,7 @@ You can also pass a number which serves as a max timeout.
 ```
 
 ::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).
 ::
 
 #### `hydrate-on-interaction`
@@ -199,7 +199,7 @@ Hydrates the component after a specified interaction (e.g., click, mouseover).
 If you do not pass an event or 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).
 ::
 
 #### `hydrate-on-media-query`
@@ -215,7 +215,7 @@ Hydrates the component when the window matches a media query.
 ```
 
 ::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).
 ::
 
 #### `hydrate-after`
@@ -430,7 +430,7 @@ This feature only works with Nuxt auto-imports and `#components` imports. Explic
 `.client` components are rendered only after being mounted. To access the rendered template using `onMounted()`, add `await nextTick()` in the callback of the `onMounted()` hook.
 ::
 
-::read-more{to="/docs/api/components/client-only"}
+::read-more{to="/docs/3.x/api/components/client-only"}
 You can also achieve a similar result with the `<ClientOnly>` component.
 ::
 
@@ -438,7 +438,7 @@ You can also achieve a similar result with the `<ClientOnly>` component.
 
 Server components allow server-rendering individual components within your client-side apps. It's possible to use server components within Nuxt, even if you are generating a static site. That makes it possible to build complex sites that mix dynamic components, server-rendered HTML and even static chunks of markup.
 
-Server components can either be used on their own or paired with a [client component](#paired-with-a-client-component).
+Server components can either be used on their own or paired with a [client component](/docs/3.x/directory-structure/components#paired-with-a-client-component).
 
 :video-accordion{title="Watch Learn Vue video about Nuxt Server Components" videoId="u1yyXe86xJM"}
 
@@ -535,6 +535,10 @@ This means:
 * You can't access the 'island context' from the rest of your app and you can't access the context of the rest of your app from the island component. In other words, the server component or island is _isolated_ from the rest of your app.
 * Your plugins will run again when rendering the island, unless they have `env: { islands: false }` set (which you can do in an object-syntax plugin).
 
+::important
+Route middleware does not run when rendering island components. Middleware is a routing concept that applies to pages, not components, and is not designed to control component rendering.
+::
+
 Within an island component, you can access its island context through `nuxtApp.ssrContext.islandContext`. Note that while island components are still marked as experimental, the format of this context may change.
 
 ::note
@@ -564,7 +568,7 @@ In this case, the `.server` + `.client` components are two 'halves' of a compone
 
 There are a number of components that Nuxt provides, including `<ClientOnly>` and `<DevOnly>`. You can read more about them in the API documentation.
 
-::read-more{to="/docs/api"}
+::read-more{to="/docs/3.x/api"}
 ::
 
 ## Library Authors
@@ -626,4 +630,4 @@ export default defineNuxtConfig({
 
 It will automatically import the components only if used and also support HMR when updating your components in `node_modules/awesome-ui/components/`.
 
-:link-example{to="/docs/examples/features/auto-imports"}
+:link-example{to="/docs/3.x/examples/features/auto-imports"}

package/2.directory-structure/1.composables.md

@@ -42,9 +42,9 @@ const foo = useFoo()
 The `composables/` directory in Nuxt does not provide any additional reactivity capabilities to your code. Instead, any reactivity within composables is achieved using Vue's Composition API mechanisms, such as ref and reactive. Note that reactive code is also not limited to the boundaries of the `composables/` directory. You are free to employ reactivity features wherever they're needed in your application.
 ::
 
-:read-more{to="/docs/guide/concepts/auto-imports"}
+:read-more{to="/docs/3.x/guide/concepts/auto-imports"}
 
-:link-example{to="/docs/examples/features/auto-imports"}
+:link-example{to="/docs/3.x/examples/features/auto-imports"}
 
 ## Types
 

package/2.directory-structure/1.content.md

@@ -5,7 +5,7 @@ description: Use the content/ directory to create a file-based CMS for your appl
 navigation.icon: i-vscode-icons-folder-type-log
 ---
 
-[Nuxt Content](https://content.nuxt.com) reads the [`content/` directory](/docs/3.x/directory-structure/content) in your project and parses `.md`, `.yml`, `.csv` and `.json` files to create a file-based CMS for your application.
+[Nuxt Content](https://content.nuxt.com) reads the `content/` directory in your project and parses `.md`, `.yml`, `.csv` and `.json` files to create a file-based CMS for your application.
 
 - Render your content with built-in components.
 - Query your content with a MongoDB-like API.

package/2.directory-structure/1.layers.md

@@ -0,0 +1,87 @@
+---
+title: 'layers'
+head.title: 'layers/'
+description: Use the layers/ directory to organize and auto-register local layers within your application.
+navigation.icon: i-vscode-icons-folder-type-nuxt
+---
+
+The `layers/` directory allows you to organize and share reusable code, components, composables, and configurations across your Nuxt application. Any layers within your project in the `layers/` directory will be automatically registered.
+
+::note
+The `layers/` directory auto-registration is available in Nuxt v3.12.0+.
+::
+
+::tip{icon="i-lucide-lightbulb"}
+Layers are ideal for organizing large codebases with **Domain-Driven Design (DDD)**, creating reusable **UI libraries** or **themes**, sharing **configuration presets** across projects, and separating concerns like **admin panels** or **feature modules**.
+::
+
+## Structure
+
+Each subdirectory within `layers/` is treated as a separate layer. A layer can contain the same structure as a standard Nuxt application.
+
+::important
+Every layer **must have** a `nuxt.config.ts` file to be recognized as a valid layer, even if it's empty.
+::
+
+```bash [Directory structure]
+-| layers/
+---| base/
+-----| nuxt.config.ts
+-----| app/
+-------| components/
+---------| BaseButton.vue
+-------| composables/
+---------| useBase.ts
+-----| server/
+-------| api/
+---------| hello.ts
+---| admin/
+-----| nuxt.config.ts
+-----| app/
+-------| pages/
+---------| admin.vue
+-------| layouts/
+---------| admin.vue
+```
+
+## Automatic Aliases
+
+Named layer aliases to the `srcDir` of each layer are automatically created. You can access a layer using the `#layers/[name]` alias:
+
+```ts
+// Access the base layer
+import something from '#layers/base/path/to/file'
+
+// Access the admin layer
+import { useAdmin } from '#layers/admin/composables/useAdmin'
+```
+
+::note
+Named layer aliases were introduced in Nuxt v3.16.0.
+::
+
+## Layer Content
+
+Each layer can include:
+
+- [`nuxt.config.ts`](/docs/3.x/directory-structure/nuxt-config) - Layer-specific configuration that will be merged with the main config
+- [`app.config.ts`](/docs/3.x/directory-structure/app-config) - Reactive application configuration
+- [`components/`](/docs/3.x/directory-structure/components) - Vue components (auto-imported)
+- [`composables/`](/docs/3.x/directory-structure/composables) - Vue composables (auto-imported)
+- [`utils/`](/docs/3.x/directory-structure/utils) - Utility functions (auto-imported)
+- [`pages/`](/docs/3.x/directory-structure/pages) - Application pages
+- [`layouts/`](/docs/3.x/directory-structure/layouts) - Application layouts
+- [`middleware/`](/docs/3.x/directory-structure/middleware) - Route middleware
+- [`plugins/`](/docs/3.x/directory-structure/plugins) - Nuxt plugins
+- [`server/`](/docs/3.x/directory-structure/server) - Server routes, middleware, and utilities
+- [`shared/`](/docs/3.x/directory-structure/shared) - Shared code between app and server
+
+## Priority Order
+
+When multiple layers define the same resource (component, composable, page, etc.), the layer with **higher priority wins**. Layers are sorted alphabetically, with later letters having higher priority (Z > A).
+
+To control the order, prefix directories with numbers: `1.base/`, `2.features/`, `3.admin/`.
+
+:read-more{to="/docs/3.x/getting-started/layers#layer-priority"}
+
+:video-accordion{title="Watch a video from Learn Vue about Nuxt Layers" videoId="lnFCM7c9f7I"}

package/2.directory-structure/1.layouts.md

@@ -24,6 +24,7 @@ Layouts are enabled by adding [`<NuxtLayout>`](/docs/3.x/api/components/nuxt-lay
 To use a layout:
 - Set a `layout` property in your page with [definePageMeta](/docs/3.x/api/utils/define-page-meta).
 - Set the `name` prop of `<NuxtLayout>`.
+- Set the `appLayout` property in route rules.
 
 ::note
 The layout name is normalized to kebab-case, so `someLayout` becomes `some-layout`.
@@ -68,13 +69,19 @@ Then you can use the `custom` layout in your page:
 
 ```vue twoslash [pages/about.vue]
 <script setup lang="ts">
+declare module 'nuxt/app' {
+  interface NuxtLayouts {
+    'custom': unknown
+  }
+}
+// ---cut---
 definePageMeta({
   layout: 'custom',
 })
 </script>
 ```
 
-::read-more{to="/docs/guide/directory-structure/pages#page-metadata"}
+::read-more{to="/docs/3.x/directory-structure/pages#page-metadata"}
 Learn more about `definePageMeta`.
 ::
 
@@ -109,7 +116,7 @@ File | Layout Name
 `~/layouts/desktop-base/DesktopBase.vue` | `desktop-base`
 `~/layouts/desktop/Desktop.vue` | `desktop`
 
-:link-example{to="/docs/examples/features/layouts"}
+:link-example{to="/docs/3.x/examples/features/layouts"}
 
 ## Changing the Layout Dynamically
 
@@ -117,6 +124,12 @@ You can also use the [`setPageLayout`](/docs/3.x/api/utils/set-page-layout) help
 
 ```vue twoslash
 <script setup lang="ts">
+declare module 'nuxt/app' {
+  interface NuxtLayouts {
+    'custom': unknown
+  }
+}
+// ---cut---
 function enableCustomLayout () {
   setPageLayout('custom')
 }
@@ -134,7 +147,26 @@ definePageMeta({
 </template>
 ```
 
-:link-example{to="/docs/examples/features/layouts"}
+You can also set layouts for specific routes using the `appLayout` property in route rules:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  routeRules: {
+    // Set layout for specific route
+    '/admin': { appLayout: 'admin' },
+    // Set layout for multiple routes
+    '/dashboard/**': { appLayout: 'dashboard' },
+    // Disable layout for a route
+    '/landing': { appLayout: false },
+  },
+})
+```
+
+::tip
+This is useful when you want to manage layouts centrally in your configuration rather than in each page file, or when you need to apply layouts to routes that don't have corresponding page components (such as catchall pages which might match many paths).
+::
+
+:link-example{to="/docs/3.x/examples/features/layouts"}
 
 ## Overriding a Layout on a Per-page Basis