@nuxt/docs 3.18.1 → 3.19.0

package/1.getting-started/07.routing.md

@@ -51,7 +51,7 @@ The [`<NuxtLink>`](/docs/api/components/nuxt-link) component links pages between
 
 When a [`<NuxtLink>`](/docs/api/components/nuxt-link) enters the viewport on the client side, Nuxt will automatically prefetch components and payload (generated pages) of the linked pages ahead of time, resulting in faster navigation.
 
-```vue [pages/app.vue]
+```vue [pages/index.vue]
 <template>
   <header>
     <nav>

package/1.getting-started/11.state-management.md

@@ -178,8 +178,8 @@ const date = useLocaleDate(new Date('2016-10-26'))
     <p>{{ date }}</p>
     <label for="locale-chooser">Preview a different locale</label>
     <select id="locale-chooser" v-model="locale">
-      <option v-for="locale of locales" :key="locale" :value="locale">
-        {{ locale }}
+      <option v-for="loc of locales" :key="loc" :value="loc">
+        {{ loc }}
       </option>
     </select>
   </div>

package/1.getting-started/14.layers.md

@@ -75,6 +75,27 @@ export default defineNuxtConfig({
 
 Nuxt uses [unjs/c12](https://c12.unjs.io) and [unjs/giget](https://giget.unjs.io) for extending remote layers. Check the documentation for more information and all available options.
 
+## Layer Priority
+
+When using multiple layers, it's important to understand how they override each other:
+
+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
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    '../base',                     // Highest priority (among extends)
+    '@my-themes/awesome',          // Medium priority
+    'github:my-themes/awesome#v1', // Lower priority
+  ]
+  // Your project has the highest priority
+})
+```
+
+This means if multiple layers define the same component, configuration, or file, the one with higher priority will be used.
+
 ::read-more{to="/docs/guide/going-further/layers"}
 Read more about layers in the **Layer Author Guide**.
 ::

package/1.getting-started/17.testing.md

@@ -54,10 +54,28 @@ We currently ship an environment for unit testing code that needs a [Nuxt](https
 2. Create a `vitest.config.ts` with the following content:
 
    ```ts twoslash
-   import { defineVitestConfig } from '@nuxt/test-utils/config'
+   import { defineConfig } from 'vitest/config'
+   import { defineVitestProject } from '@nuxt/test-utils/config'
 
-   export default defineVitestConfig({
-     // any custom Vitest config you require
+   export default defineConfig({
+     test: {
+       projects: [
+         {
+           test: {
+             name: 'unit',
+             include: ['test/{e2e,unit}/*.{test,spec}.ts'],
+             environment: 'node',
+           },
+         },
+         await defineVitestProject({
+           test: {
+             name: 'nuxt',
+             include: ['test/nuxt/*.{test,spec}.ts'],
+             environment: 'nuxt',
+           },
+         }),
+       ],
+     },
    })
    ```
 
@@ -72,24 +90,16 @@ It is possible to set environment variables for testing by using the `.env.test`
 
 ### Using a Nuxt Runtime Environment
 
-By default, `@nuxt/test-utils` will not change your default Vitest environment, so you can do fine-grained opt-in and run Nuxt tests together with other unit tests.
+Using [Vitest projects](https://vitest.dev/guide/projects.html#test-projects), you have fine-grained control over which tests run in which environment:
 
-You can opt in to a Nuxt environment by adding `.nuxt.` to the test file's name (for example, `my-file.nuxt.test.ts` or `my-file.nuxt.spec.ts`) or by adding `@vitest-environment nuxt` as a comment directly in the test file.
+- **Unit tests**: Place regular unit tests in `test/unit/` - these run in a Node environment for speed
+- **Nuxt tests**: Place tests that rely on the Nuxt runtime environment in `test/nuxt/` - these will run within a Nuxt runtime environment
 
-   ```ts twoslash
-   // @vitest-environment nuxt
-   import { test } from 'vitest'
+#### Alternative: Simple Setup
 
-   test('my test', () => {
-     // ... test with Nuxt environment!
-   })
-   ```
-
-You can alternatively set `environment: 'nuxt'` in your Vitest configuration to enable the Nuxt environment for **all tests**.
+If you prefer a simpler setup and want all tests to run in the Nuxt environment, you can use the basic configuration:
 
 ```ts twoslash
-// vitest.config.ts
-import { fileURLToPath } from 'node:url'
 import { defineVitestConfig } from '@nuxt/test-utils/config'
 
 export default defineVitestConfig({
@@ -109,7 +119,7 @@ export default defineVitestConfig({
 })
 ```
 
-If you have set `environment: 'nuxt'` by default, you can then opt _out_ of the [default environment](https://vitest.dev/guide/environment.html#test-environment) per test file as needed.
+If you're using the simple setup with `environment: 'nuxt'` by default, you can opt _out_ of the [Nuxt environment](https://vitest.dev/guide/environment.html#test-environment) per test file as needed.
 
 ```ts twoslash
 // @vitest-environment node
@@ -120,6 +130,45 @@ test('my test', () => {
 })
 ```
 
+::warning
+This approach is not recommended as it creates a hybrid environment where Nuxt Vite plugins run but the Nuxt entry and `nuxtApp` are not initialized. This can lead to hard-to-debug errors.
+::
+
+### Organizing Your Tests
+
+With the project-based setup, you might organize your tests as follows:
+
+```bash [Directory structure]
+test/
+├── e2e/
+│   └── ssr.test.ts
+├── nuxt/
+│   ├── components.test.ts
+│   └── composables.test.ts
+├── unit/
+│   └── utils.test.ts
+```
+
+You can of course opt for any test structure, but keeping the Nuxt runtime environment separated from Nuxt end-to-end tests is important for test stability.
+
+#### Running Tests
+
+With the project setup, you can run different test suites:
+
+```bash
+# Run all tests
+npx vitest
+
+# Run only unit tests
+npx vitest --project unit
+
+# Run only Nuxt tests
+npx vitest --project nuxt
+
+# Run tests in watch mode
+npx vitest --watch
+```
+
 ::warning
 When you run your tests within the Nuxt environment, they will be running in a [`happy-dom`](https://github.com/capricorn86/happy-dom) or [`jsdom`](https://github.com/jsdom/jsdom) environment. Before your tests run, a global Nuxt app will be initialized (including, for example, running any plugins or code you've defined in your `app.vue`).
 
@@ -555,7 +604,11 @@ Please use the options below for the `setup` method.
 
 - `setupTimeout`: The amount of time (in milliseconds) to allow for `setupTest` to complete its work (which could include building or generating files for a Nuxt application, depending on the options that are passed).
   - Type: `number`
-  - Default: `60000`
+  - Default: `120000` or `240000` on windows
+
+- `teardownTimeout`: The amount of time (in milliseconds) to allow tearing down the test environment, such as closing the browser.
+  - Type: `number`
+  - Default: `30000`
 
 #### Features
 

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

@@ -1129,7 +1129,16 @@ However, to take advantage of improved type checking, you can opt in to the new
    + "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
    ```
 
-4. **Configure Node.js TypeScript options** if needed:
+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.
+
+    ::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:
    <!-- @case-police-ignore tsConfig -->
 
    ```ts
@@ -1151,7 +1160,7 @@ However, to take advantage of improved type checking, you can opt in to the new
    })
    ```
 
-5. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.
+6. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.
 
 The new configuration provides better type safety and IntelliSense for projects that opt in, while maintaining full backward compatibility for existing setups.
 

package/2.guide/1.concepts/8.typescript.md

@@ -80,6 +80,20 @@ Overwriting options such as `"compilerOptions.paths"` with your own configuratio
 In case you need to extend options provided by `./.nuxt/tsconfig.json` further, you can use the [`alias` property](/docs/api/nuxt-config#alias) within your `nuxt.config`. Nuxt will pick them up and extend `./.nuxt/tsconfig.json` accordingly.
 ::
 
+### Augmenting Types with Project References
+
+Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they are properly recognized.
+
+For example, if you want to augment types for the `app` context, the augmentation file should be placed in the `app/` directory.
+
+Similarly:
+- For the `server` context, place the augmentation file in the `server/` directory.
+- For types that are **shared between the app and server**, place the file in the `shared/` directory.
+
+::warning
+Augmenting types outside of these directories will not be recognized by TypeScript.
+::
+
 ## Strict Checks
 
 TypeScript comes with certain checks to give you more safety and analysis of your program.

package/2.guide/2.directory-structure/1.middleware.md

@@ -142,6 +142,44 @@ This is true even if you throw an error in your middleware on the server, and an
 Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/getting-started/error-handling#useerror) in middleware to check if an error is being handled.
 ::
 
+## Accessing Route in Middleware
+
+Always use the `to` and `from` parameters in your middleware to access the next and previous routes. Avoid using the [`useRoute()`](/docs/api/composables/use-route) composable in this context altogether.
+There is **no concept of a "current route" in middleware**, as middleware can abort a navigation or redirect to a different route. The `useRoute()` composable will always be inaccurate in this context.  
+
+::warning
+Sometimes, you might call a composable that uses `useRoute()` internally, which can trigger this warning even if there is no direct call in your middleware.
+This leads to the **same issue as above**, so you should structure your functions to accept the route as an argument instead when they are used in middleware.
+::
+
+::code-group
+```ts twoslash [middleware/access-route.ts]
+// @errors: 2304
+export default defineNuxtRouteMiddleware(to => {
+  // passing the route to the function to avoid calling `useRoute()` in middleware
+  doSomethingWithRoute(to)
+    
+  // ❌ this will output a warning and is NOT recommended
+  callsRouteInternally()
+})
+```
+
+```ts twoslash [utils/handle-route.ts]
+// providing the route as an argument so that it can be used in middleware correctly
+export function doSomethingWithRoute(route = useRoute()) {
+  // ...
+}
+```
+```ts twoslash [utils/dont-do-this.ts]
+// ❌ this function is not suitable for use in middleware
+export function callsRouteInternally() {
+    const route = useRoute()
+  // ...
+}
+```
+
+::
+
 ## Adding Middleware Dynamically
 
 It is possible to add global or named route middleware manually using the [`addRouteMiddleware()`](/docs/api/utils/add-route-middleware) helper function, such as from within a plugin.

package/2.guide/2.directory-structure/1.pages.md

@@ -337,7 +337,7 @@ You may define a path matcher, if you have a more complex pattern than can be ex
 
 #### `props`
 
-Allows accessing the route `params` as props passed to the page component. See[the `vue-router` docs](https://router.vuejs.org/guide/essentials/passing-props) for more information.
+Allows accessing the route `params` as props passed to the page component. See [the `vue-router` docs](https://router.vuejs.org/guide/essentials/passing-props) for more information.
 
 ### Typing Custom Metadata
 

package/2.guide/3.going-further/1.experimental-features.md

@@ -688,3 +688,36 @@ export default defineNuxtConfig({
   }
 })
 ```
+
+## entryImportMap
+
+By default, Nuxt improves chunk stability by using an import map to resolve the entry chunk of the bundle.
+
+This injects an import map at the top of your `<head>` tag:
+
+```html
+<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>
+```
+
+Within the script chunks emitted by Vite, imports will be from `#entry`. This means that changes to the entry will not invalidate chunks which are otherwise unchanged.
+
+::note
+Nuxt smartly disables this feature if you have configured `vite.build.target` to include a browser that doesn't support import maps, or if you have configured `vite.build.rollupOptions.output.entryFileNames` to a value that does not include `[hash]`.
+::
+
+If you need to disable this feature you can do so:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    entryImportMap: false
+  },
+// or, better, simply tell vite your desired target
+  // which nuxt will respect
+  vite: {
+    build: {
+      target: 'safari13'
+    },
+  },
+})
+```

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

@@ -177,6 +177,23 @@ export default defineNuxtModule({
   defaults: {},
   // Shorthand sugar to register Nuxt hooks
   hooks: {},
+  // Configuration for other modules - this does not ensure the module runs before
+  // your module, but it allows you to change the other module's configuration before it runs
+  moduleDependencies: {
+    'some-module': {
+      // You can specify a version constraint for the module. If the user has a different
+      // version installed, Nuxt will throw an error on startup.
+      version: '>=2',
+      // By default moduleDependencies will be added to the list of modules to be installed
+      // by Nuxt unless `optional` is set.
+      optional: true,
+      // Any configuration that should override `nuxt.options`.
+      overrides: {},
+      // Any configuration that should be set. It will override module defaults but
+      // will not override any configuration set in `nuxt.options`.
+      defaults: {}
+    }
+  },
   // The function holding your module logic, it can be asynchronous
   setup(moduleOptions, nuxt) {
     // ...

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

@@ -18,6 +18,7 @@ Additionally, certain other files in the layer directory will be auto-scanned an
 - [`components/*`](/docs/guide/directory-structure/components)   - Extend the default components
 - [`composables/*`](/docs/guide/directory-structure/composables)  - Extend the default composables
 - [`layouts/*`](/docs/guide/directory-structure/layouts)  - Extend the default layouts
+- [`middleware/*`](/docs/guide/directory-structure/middleware)  - Extend the default middleware
 - [`pages/*`](/docs/guide/directory-structure/pages)        - Extend the default pages
 - [`plugins/*`](/docs/guide/directory-structure/plugins)        - Extend the default plugins
 - [`server/*`](/docs/guide/directory-structure/server)       - Extend the default server endpoints & middleware
@@ -65,6 +66,29 @@ 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:
+
+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
+
+For example:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  extends: [
+    './layers/base',      // Highest priority (among extends)
+    './layers/theme',     // Medium priority  
+    './layers/custom'     // Lower priority
+  ]
+  // 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.
+
 ## Starter Template
 
 To get started you can initialize a layer with the [nuxt/starter/layer template](https://github.com/nuxt/starter/tree/layer). This will create a basic structure you can build upon. Execute this command within the terminal to get started:

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

@@ -12,6 +12,12 @@ links:
 Within the template of a Vue component, you can access the route using `$route`.
 ::
 
+The `useRoute` composable is a wrapper around the identically named composable from `vue-router`, providing access to the current route in a Nuxt application.
+
+The key difference is that in Nuxt, the composable ensures that the route is updated **only after** the page content has changed after navigation.
+In contrast, the `vue-router` version updates the route **immediately**, which can lead to synchronization issues between different parts of the template
+that rely on the route metadata, for example.
+
 ## Example
 
 In the following example, we call an API via [`useFetch`](/docs/api/composables/use-fetch) using a dynamic page parameter - `slug` - as part of the URL.
@@ -45,8 +51,37 @@ Apart from dynamic parameters and query parameters, `useRoute()` also provides t
 - `path`: encoded pathname section of the URL
 - `redirectedFrom`: route location that was attempted to access before ending up on the current route location
 
-::note
-Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` in your template can trigger hydration issues because this will include the fragment on client but not the server.
+## Common Pitfalls
+
+### Route Synchronization Issues
+
+It’s important to use the `useRoute()` composable from Nuxt rather than the one from `vue-router` to avoid synchronization issues during page navigation.
+Importing `useRoute` directly from `vue-router` bypasses Nuxt's implementation.
+
+```ts twoslash
+// ❌ do not use `useRoute` from `vue-router`
+// @errors: 2300
+import { useRoute } from 'vue-router'
+// ✅ use Nuxt's `useRoute` composable
+import { useRoute } from '#app'
+```
+
+### Calling `useRoute` in Middleware
+
+Using `useRoute` in middleware is not recommended because it can lead to unexpected behavior.
+There is no concept of a "current route" in middleware.
+The `useRoute()` composable should only be used in the setup function of a Vue component or in a Nuxt plugin.
+
+::warning
+This applies to any composable that uses `useRoute()` internally too.
 ::
 
+::read-more{to="/docs/4.x/guide/directory-structure/app/middleware"}
+Read more about accessing the route in the middleware section.
+::
+
+### Hydration Issues with `route.fullPath`
+
+Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` to affect the template can trigger hydration issues because this will include the fragment on client but not the server.
+
 :read-more{icon="i-simple-icons-vuedotjs" to="https://router.vuejs.org/api/type-aliases/RouteLocationNormalizedLoaded.html"}

package/3.api/4.commands/init.md

@@ -10,7 +10,7 @@ links:
 
 <!--init-cmd-->
 ```bash [Terminal]
-npm create nuxt@latest [DIR] [--cwd=<directory>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager]
+npm create nuxt@latest [DIR] [--cwd=<directory>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager] [--nightly]
 ```
 <!--/init-cmd-->
 
@@ -40,6 +40,7 @@ Option | Default | Description
 `--packageManager` |  | Package manager choice (npm, pnpm, yarn, bun)
 `--modules` |  | Nuxt modules to install (comma separated without spaces)
 `--no-modules` |  | Skip module installation prompt
+`--nightly` |  | Use Nuxt nightly release channel (3x or latest)
 <!--/init-opts-->
 
 ## Environment variables

package/3.api/5.kit/16.layers.md

@@ -0,0 +1,220 @@
+---
+title: "Layers"
+description: Nuxt Kit provides utilities to help you work with layers and their directory structures.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/layers.ts
+    size: xs
+---
+
+Nuxt layers provide a powerful way to share and extend functionality across projects. When working with layers in modules, you often need to access directory paths from each layer. Nuxt Kit provides the `getLayerDirectories` utility to access resolved directory paths for all layers in your Nuxt application.
+
+## `getLayerDirectories`
+
+Get the resolved directory paths for all layers in a Nuxt application. This function provides a structured way to access layer directories without directly accessing the private `nuxt.options._layers` property.
+
+### Usage
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Access directories from all layers
+    for (const [index, layer] of layerDirs.entries()) {
+      console.log(`Layer ${index}:`)
+      console.log(`  Root: ${layer.root}`)
+      console.log(`  App: ${layer.app}`)
+      console.log(`  Server: ${layer.server}`)
+      console.log(`  Pages: ${layer.appPages}`)
+      // ... other directories
+    }
+  }
+})
+```
+
+### Type
+
+```ts twoslash
+// @errors: 2391
+import type { Nuxt } from '@nuxt/schema'
+// ---cut---
+function getLayerDirectories(nuxt?: Nuxt): LayerDirectories[]
+
+interface LayerDirectories {
+  /** Nuxt rootDir (`/` by default) */
+  readonly root: string
+  /** Nitro source directory (`/server` by default) */
+  readonly server: string
+  /** Local modules directory (`/modules` by default) */
+  readonly modules: string
+  /** Shared directory (`/shared` by default) */
+  readonly shared: string
+  /** Public directory (`/public` by default) */
+  readonly public: string
+  /** Nuxt srcDir (`/app/` by default) */
+  readonly app: string
+  /** Layouts directory (`/app/layouts` by default) */
+  readonly appLayouts: string
+  /** Middleware directory (`/app/middleware` by default) */
+  readonly appMiddleware: string
+  /** Pages directory (`/app/pages` by default) */
+  readonly appPages: string
+  /** Plugins directory (`/app/plugins` by default) */
+  readonly appPlugins: string
+}
+```
+
+### Parameters
+
+**`nuxt`** (optional): The Nuxt instance to get layers from. If not provided, the function will use the current Nuxt context.
+
+### Return Value
+
+The `getLayerDirectories` function returns an array of `LayerDirectories` objects, one for each layer in the application.
+
+**Layer Priority Ordering**: The layers are ordered by priority, where:
+- The **first layer** is the user/project layer (highest priority)
+- **Earlier layers override later layers** in the array
+- **Base layers appear last** in the array (lowest priority)
+
+This ordering matches Nuxt's layer resolution system, where user-defined configurations and files take precedence over those from base layers.
+
+**`LayerDirectories`**: An object containing the resolved directory paths for a layer.
+
+| Property        | Type     | Description                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------------ |
+| `root`          | `string` | The root directory of the layer (equivalent to `rootDir`)                     |
+| `server`        | `string` | The server directory for Nitro server-side code                               |
+| `modules`       | `string` | The local modules directory                                                    |
+| `shared`        | `string` | The shared directory for code used by both client and server                  |
+| `app`           | `string` | The source directory of the layer (equivalent to `srcDir`)                    |
+| `public`        | `string` | The public directory for static assets                                         |
+| `appLayouts`    | `string` | The layouts directory for Vue layout components                                |
+| `appMiddleware` | `string` | The middleware directory for route middleware                                  |
+| `appPages`      | `string` | The pages directory for file-based routing                                    |
+| `appPlugins`    | `string` | The plugins directory for Nuxt plugins                                        |
+
+### Examples
+
+**Processing files from all layers:**
+
+```ts twoslash
+// @errors: 2307
+// ---cut---
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+import { resolve } from 'pathe'
+import { globby } from 'globby'
+
+export default defineNuxtModule({
+  async setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Find all component files across layers
+    // Note: layerDirs[0] is the user layer (highest priority)
+    // Later layers in the array have lower priority
+    const componentFiles = []
+    for (const [index, layer] of layerDirs.entries()) {
+      const files = await globby('**/*.vue', {
+        cwd: resolve(layer.app, 'components'),
+        absolute: true
+      })
+      console.log(`Layer ${index} (${index === 0 ? 'user' : 'base'}):`, files.length, 'components')
+      componentFiles.push(...files)
+    }
+  }
+})
+```
+
+**Adding templates from multiple layers:**
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories, addTemplate } from '@nuxt/kit'
+import { resolve, basename } from 'pathe'
+import { existsSync } from 'fs'
+
+export default defineNuxtModule({
+  async setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Add a config file from each layer that has one
+    for (const dirs of layerDirs) {
+      const configPath = resolve(dirs.app, 'my-module.config.ts')
+      if (existsSync(configPath)) {
+        addTemplate({
+          filename: `my-module-${basename(dirs.root)}.config.ts`,
+          src: configPath
+        })
+      }
+    }
+  }
+})
+```
+
+**Respecting layer priority:**
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+import { resolve } from 'pathe'
+import { existsSync, readFileSync } from 'fs'
+
+export default defineNuxtModule({
+  setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Find the first (highest priority) layer that has a specific config file
+    // This respects the layer priority system
+    let configContent = null
+    for (const dirs of layerDirs) {
+      const configPath = resolve(dirs.app, 'my-config.json')
+      if (existsSync(configPath)) {
+        configContent = readFileSync(configPath, 'utf-8')
+        console.log(`Using config from layer: ${dirs.root}`)
+        break // Use the first (highest priority) config found
+      }
+    }
+    
+    // Alternative: Collect configs from all layers, with user layer taking precedence
+    const allConfigs = {}
+    for (const dirs of layerDirs.reverse()) { // Process from lowest to highest priority
+      const configPath = resolve(dirs.app, 'my-config.json')
+      if (existsSync(configPath)) {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+        Object.assign(allConfigs, config) // Later assignments override earlier ones
+      }
+    }
+  }
+})
+```
+
+**Checking for layer-specific directories:**
+
+```ts twoslash
+import { defineNuxtModule, getLayerDirectories } from '@nuxt/kit'
+import { existsSync } from 'fs'
+import { resolve } from 'pathe'
+
+export default defineNuxtModule({
+  setup() {
+    const layerDirs = getLayerDirectories()
+    
+    // Find layers that have a specific custom directory
+    const layersWithAssets = layerDirs.filter(layer => {
+      return existsSync(resolve(layer.app, 'assets'))
+    })
+    
+    console.log(`Found ${layersWithAssets.length} layers with assets directory`)
+  }
+})
+```
+
+::note
+The `getLayerDirectories` function includes caching via a WeakMap to avoid recomputing directory paths for the same layers repeatedly, improving performance when called multiple times.
+::
+
+::note
+Directory paths returned by this function always include a trailing slash for consistency.
+::

package/5.community/6.roadmap.md

@@ -59,17 +59,17 @@ We commit to support each major version of Nuxt for a minimum of six months afte
 
 ### Current Packages
 
-The current active version of [Nuxt](https://nuxt.com) is **v3** which is available as `nuxt` on npm with the `latest` tag.
+The current active version of [Nuxt](https://nuxt.com) is **v4** which is available as `nuxt` on npm with the `latest` tag.
 
-Nuxt 2 is in maintenance mode and is available on npm with the `2x` tag. It reached End of Life (EOL) on June 30, 2024.
+Nuxt 3 will continue to receive maintenance updates (both bug fixes and backports of features from Nuxt 4) until the end of January 2026.
 
 Each active version has its own nightly releases which are generated automatically. For more about enabling the Nuxt nightly release channel, see [the nightly release channel docs](/docs/guide/going-further/nightly-release-channel).
 
-Release                                 |                                                                                                  | Initial release | End Of Life  | Docs
-----------------------------------------|---------------------------------------------------------------------------------------------------|-----------------|--------------|-------
+Release                    |                                                                                                                                                                               | Initial release       | End Of Life                  | Docs
+-------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------- | ---------------------------------------
 **5.x** (scheduled)        |                                                                                                                                                                               | Q4 2025 (estimated)   | TBA                          |  
-**4.x** (scheduled)        |                                                                                                                                                                               | 2025-06-30 (planned)  | 6 months after 5.x release   |  
-**3.x** (stable)           | <a href="https://npmjs.com/package/nuxt"><img alt="Nuxt latest 3.x version" src="https://flat.badgen.net/npm/v/nuxt?label=" class="not-prose"></a>                            | 2022-11-16            | 2025-12-31 (TBC)             | [nuxt.com](/docs)
+**4.x** (stable)           | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt latest version" src="https://flat.badgen.net/npm/v/nuxt?label=" class="not-prose"></a>         | 2025-07-16            | 6 months after 5.x release   | [nuxt.com](/docs/4.x)
+**3.x** (maintenance)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 3.x version" src="https://flat.badgen.net/npm/v/nuxt/3x?label=" class="not-prose"></a>         | 2022-11-16            | 2026-01-31                   | [nuxt.com](/docs/3.x)
 **2.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 2.x version" src="https://flat.badgen.net/npm/v/nuxt/2x?label=" class="not-prose"></a>         | 2018-09-21            | 2024-06-30                   | [v2.nuxt.com](https://v2.nuxt.com/docs)
 **1.x** (unsupported)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 1.x version" src="https://flat.badgen.net/npm/v/nuxt/1x?label=" class="not-prose"></a>         | 2018-01-08            | 2019-09-21                   | &nbsp;
 

package/package.json

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