@nuxt/docs 4.0.2 → 4.1.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

@@ -1072,7 +1072,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
@@ -1094,7 +1103,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/10.nuxt-lifecycle.md

@@ -68,7 +68,7 @@ In Nuxt, there are three types of middleware:
 - **Named route middleware**
 - **Anonymous (or inline) route middleware**
 
-Nuxt automatically executes global middleware for first time enter to the application and every time before route navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
+Nuxt executes all global middleware on the initial page load (both on server and client) and then again before any client-side navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
 
 For details about each type and examples, see the [Middleware documentation](/docs/guide/directory-structure/middleware).
 

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

@@ -108,6 +108,20 @@ Each of these files is configured to reference the appropriate dependencies and
 The project reference setup is handled automatically by Nuxt. You typically don't need to modify these configurations manually, but understanding how they work can help you troubleshoot type-checking issues.
 ::
 
+### 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.app/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.app/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/2.directory-structure/2.nuxtrc.md

@@ -27,6 +27,10 @@ modules[]=nuxt-security
 
 If present, the properties in the `nuxt.config` file will overwrite the properties in `.nuxtrc` file.
 
+::note
+Nuxt automatically adds a `setups` section to track module installation and upgrade state. This is used internally for [module lifecycle hooks](/docs/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) and should not be modified manually.
+::
+
 ::read-more{to="/docs/api/configuration/nuxt-config"}
 Discover all the available options in the **Nuxt configuration** documentation.
 ::

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

@@ -637,3 +637,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) {
     // ...
@@ -763,6 +780,38 @@ Nuxt Modules should provide an explicit prefix for any exposed configuration, pl
 
 Ideally, you should prefix them with your module's name (e.g. if your module is called `nuxt-foo`, expose `<FooButton>` and `useFooBar()` and **not** `<Button>` and `useBar()`).
 
+#### Use Lifecycle Hooks for One-Time Setup
+
+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/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.

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

@@ -15,15 +15,16 @@ 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.
 
-- [`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
-- [`pages/*`](/docs/guide/directory-structure/pages)        - Extend the default pages
-- [`plugins/*`](/docs/guide/directory-structure/plugins)        - Extend the default plugins
+- [`app/components/*`](/docs/guide/directory-structure/components)   - Extend the default components
+- [`app/composables/*`](/docs/guide/directory-structure/composables)  - Extend the default composables
+- [`app/layouts/*`](/docs/guide/directory-structure/layouts)  - Extend the default layouts
+- [`app/middleware/*`](/docs/guide/directory-structure/middleware)  - Extend the default middleware
+- [`app/pages/*`](/docs/guide/directory-structure/pages)        - Extend the default pages
+- [`app/plugins/*`](/docs/guide/directory-structure/plugins)        - Extend the default plugins
+- [`app/utils/*`](/docs/guide/directory-structure/utils)   - Extend the default utils
+- [`app/app.config.ts`](/docs/guide/directory-structure/app-config)  - Extend the default app config
 - [`server/*`](/docs/guide/directory-structure/server)       - Extend the default server endpoints & middleware
-- [`utils/*`](/docs/guide/directory-structure/utils)   - Extend the default utils
 - [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt-config)- Extend the default nuxt config
-- [`app.config.ts`](/docs/guide/directory-structure/app-config)  - Extend the default app config
 
 ## Basic Example
 
@@ -57,7 +58,7 @@ Additionally, certain other files in the layer directory will be auto-scanned an
     })
   ```
 
-  ```vue [base/components/BaseComponent.vue]
+  ```vue [base/app/components/BaseComponent.vue]
     <template>
       <h1>Extending Components is Fun!</h1>
     </template>
@@ -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:
@@ -194,7 +218,7 @@ const currentDir = dirname(fileURLToPath(import.meta.url))
 
 export default defineNuxtConfig({
   css: [
-    join(currentDir, './assets/main.css')
+    join(currentDir, './app/assets/main.css')
   ]
 })
 ```

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

@@ -49,7 +49,8 @@ You may need to update the config below with a path to your web browser. For mor
       "request": "launch",
       "name": "client: chrome",
       "url": "http://localhost:3000",
-      "webRoot": "${workspaceFolder}"
+      // this should point to your Nuxt `srcDir`, which is `app` by default
+      "webRoot": "${workspaceFolder}/app"
     },
     {
       "type": "node",

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/1.modules.md

@@ -62,6 +62,8 @@ export function defineNuxtModule<TOptions extends ModuleOptions> (): {
 | `defaults`         | `T \| ((nuxt: Nuxt) => T)`{lang="ts"}                                | `false`  | Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument. |
 | `schema`           | `T`                                                                  | `false`  | Schema for the module options. If provided, options will be applied to the schema.                              |
 | `hooks`            | `Partial<NuxtHooks>`{lang="ts"}                                      | `false`  | Hooks to be installed for the module. If provided, the module will install the hooks.                           |
+| `onInstall`        | `(nuxt: Nuxt) => Awaitable<void>`{lang="ts"}                        | `false`  | Lifecycle hook called when the module is first installed. Requires `meta.name` and `meta.version` to be defined. |
+| `onUpgrade`        | `(options: T, nuxt: Nuxt, previousVersion: string) => Awaitable<void>`{lang="ts"} | `false`  | Lifecycle hook called when the module is upgraded to a newer version. Requires `meta.name` and `meta.version` to be defined. |
 | `setup`            | `(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void \| false \| ModuleSetupInstallResult>`{lang="ts"} | `false`  | Setup function for the module. If provided, the module will call the setup function.    |
 
 ### Examples
@@ -171,6 +173,72 @@ export default defineNuxtModule<ModuleOptions>().with({
 
 Without using `.with()`, the `resolvedOptions` parameter would be typed as the raw `ModuleOptions` interface, where `timeout` and `retries` could be `undefined` even when defaults are provided. The `.with()` method enables TypeScript to understand that default values make those properties non-optional in the resolved options.
 
+#### Using Lifecycle Hooks for Module Installation and Upgrade
+
+You can define lifecycle hooks that run when your module is first installed or upgraded to a new version. These hooks are useful for performing one-time setup tasks, database migrations, or cleanup operations.
+
+::important
+For lifecycle hooks to work, you **must** provide both `meta.name` and `meta.version` in your module definition. The hooks use these values to track the module's installation state in the project's `.nuxtrc` file.
+::
+
+Lifecycle hooks run before the main `setup` function, and if a hook throws an error, it's logged but doesn't stop the build process.
+
+**`onInstall`** runs only once when the module is first added to a project.
+
+**`onUpgrade`** runs each time the module version increases (using semver comparison) &mdash; but only once for each version bump.
+
+##### Example
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+import semver from 'semver'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-awesome-module',
+    version: '1.2.0', // Required for lifecycle hooks
+    configKey: 'myAwesomeModule'
+  },
+  defaults: {
+    apiKey: '',
+    enabled: true
+  },
+  
+  onInstall(nuxt) {
+    // This runs only when the module is first installed
+    console.log('Setting up my-awesome-module for the first time!')
+    
+    // You might want to:
+    // - Create initial configuration files
+    // - Set up database schemas
+    // - Display welcome messages
+    // - Perform initial data migration
+  },
+  
+  onUpgrade(options, nuxt, previousVersion) {
+    // This runs when the module is upgraded to a newer version
+    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)
+    
+    // You might want to:
+    // - Migrate configuration files
+    // - Update database schemas  
+    // - Clean up deprecated files
+    // - Display upgrade notes
+    
+    if (semver.lt(previousVersion, '1.1.0')) {
+      console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
+    }
+  },
+  
+  setup(options, nuxt) {
+    // Regular setup logic runs on every build
+    if (options.enabled) {
+      // Configure the module
+    }
+  }
+})
+```
+
 ## `installModule`
 
 Install specified Nuxt module programmatically. This is helpful when your module depends on other modules. You can pass the module options as an object to `inlineOptions` and they will be passed to the module's `setup` function.

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/3.api/6.nuxt-config.md

@@ -19,7 +19,7 @@ You can improve your DX by defining additional aliases to access custom director
   "@@": "/<rootDir>",
   "#shared": "/<rootDir>/shared",
   "assets": "/<srcDir>/assets",
-  "public": "/<srcDir>/public",
+  "public": "/<rootDir>/public",
   "#build": "/<rootDir>/.nuxt",
   "#internal/nuxt/paths": "/<rootDir>/.nuxt/paths.mjs"
 }
@@ -252,7 +252,15 @@ Customize Nuxt root element tag.
 
 ### `spaLoaderAttrs`
 
-Customize Nuxt Nuxt SpaLoader element attributes.
+Customize Nuxt SPA loading template element attributes.
+
+- **Type**: `object`
+- **Default:**
+```json
+{
+"id": "__nuxt-loader"
+}
+```
 
 #### `id`
 
@@ -1266,7 +1274,7 @@ Inline styles when rendering HTML (currently vite only).
 You can also pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component.
 
 - **Type**: `boolean`
-- **Default:** `true`
+- **Default:** `(id) => id.includes('.vue')`
 
 ### `noScripts`
 

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": "4.0.2",
+  "version": "4.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",