@nuxt/docs 4.0.3 → 4.1.1

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

@@ -13,7 +13,7 @@ For best performance, components placed in this directory will be automatically
 
 Layouts are enabled by adding [`<NuxtLayout>`](/docs/api/components/nuxt-layout) to your [`app.vue`](/docs/guide/directory-structure/app):
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLayout>
     <NuxtPage />
@@ -30,7 +30,7 @@ The layout name is normalized to kebab-case, so `someLayout` becomes `some-layou
 ::
 
 ::note
-If no layout is specified, `layouts/default.vue` will be used.
+If no layout is specified, `app/layouts/default.vue` will be used.
 ::
 
 ::important
@@ -45,7 +45,7 @@ Unlike other components, your layouts must have a single root element to allow N
 
 Add a `~/layouts/default.vue`:
 
-```vue [layouts/default.vue]
+```vue [app/layouts/default.vue]
 <template>
   <div>
     <p>Some default layout content shared across all pages</p>
@@ -74,13 +74,13 @@ definePageMeta({
 </script>
 ```
 
-::read-more{to="/docs/guide/directory-structure/pages#page-metadata"}
+::read-more{to="/docs/guide/directory-structure/app/pages#page-metadata"}
 Learn more about `definePageMeta`.
 ::
 
 You can directly override the default layout for all pages using the `name` property of [`<NuxtLayout>`](/docs/api/components/nuxt-layout):
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup lang="ts">
 // You might choose this based on an API call or logged-in status
 const layout = "custom";
@@ -140,7 +140,7 @@ If you are using pages, you can take full control by setting `layout: false` and
 
 ::code-group
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 definePageMeta({
   layout: false,
@@ -158,7 +158,7 @@ definePageMeta({
 </template>
 ```
 
-```vue [layouts/custom.vue]
+```vue [app/layouts/custom.vue]
 <template>
   <div>
     <header>

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

@@ -10,8 +10,8 @@ Nuxt provides a customizable **route middleware** framework you can use througho
 There are three kinds of route middleware:
 
 1. Anonymous (or inline) route middleware are defined directly within the page.
-2. Named route middleware, placed in the `middleware/` and automatically loaded via asynchronous import when used on a page.
-3. Global route middleware, placed in the `middleware/` with a `.global` suffix and is run on every route change.
+2. Named route middleware, placed in the `app/middleware/` and automatically loaded via asynchronous import when used on a page.
+3. Global route middleware, placed in the `app/middleware/` with a `.global` suffix and is run on every route change.
 
 The first two kinds of route middleware can be defined in [`definePageMeta`](/docs/api/utils/define-page-meta).
 
@@ -74,7 +74,7 @@ Middleware runs in the following order:
 
 For example, assuming you have the following middleware and component:
 
-```bash [middleware/ directory]
+```bash [app/middleware/ directory]
 -| middleware/
 ---| analytics.global.ts
 ---| setup.global.ts
@@ -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

@@ -17,7 +17,7 @@ Nuxt will automatically create a route for every page in your `~/pages/` directo
 
 ::code-group
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <template>
   <h1>Index page</h1>
 </template>
@@ -44,11 +44,11 @@ export default defineComponent({
 
 ::
 
-The `pages/index.vue` file will be mapped to the `/` route of your application.
+The `app/pages/index.vue` file will be mapped to the `/` route of your application.
 
 If you are using [`app.vue`](/docs/guide/directory-structure/app), make sure to use the [`<NuxtPage/>`](/docs/api/components/nuxt-page) component to display the current page:
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <div>
     <!-- Markup shared across all pages, ex: NavBar -->
@@ -65,7 +65,7 @@ Here are some examples to illustrate what a page with a single root element look
 
 ::code-group
 
-```vue [pages/working.vue]
+```vue [app/pages/working.vue]
 <template>
   <div>
     <!-- This page correctly has only one single root element -->
@@ -74,14 +74,14 @@ Here are some examples to illustrate what a page with a single root element look
 </template>
 ```
 
-```vue [pages/bad-1.vue]
+```vue [app/pages/bad-1.vue]
 <template>
   <!-- This page will not render when route changes during client side navigation, because of this comment -->
   <div>Page content</div>
 </template>
 ```
 
-```vue [pages/bad-2.vue]
+```vue [app/pages/bad-2.vue]
 <template>
   <div>This page</div>
   <div>Has more than one root element</div>
@@ -106,7 +106,7 @@ If you want a parameter to be _optional_, you must enclose it in double square b
 
 Given the example above, you can access group/id within your component via the `$route` object:
 
-```vue [pages/users-[group\\]/[id\\].vue]
+```vue [app/pages/users-[group\\]/[id\\].vue]
 <template>
   <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
 </template>
@@ -140,7 +140,7 @@ Named parent routes will take priority over nested dynamic routes. For the `/foo
 
 If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path.
 
-```vue [pages/[...slug\\].vue]
+```vue [app/pages/[...slug\\].vue]
 <template>
   <p>{{ $route.params.slug }}</p>
 </template>
@@ -184,7 +184,7 @@ This file tree will generate these routes:
 ]
 ```
 
-To display the `child.vue` component, you have to insert the `<NuxtPage>` component inside `pages/parent.vue`:
+To display the `child.vue` component, you have to insert the `<NuxtPage>` component inside `app/pages/parent.vue`:
 
 ```vue {}[pages/parent.vue]
 <template>
@@ -315,7 +315,7 @@ You can set a default value for this property [in your `nuxt.config`](/docs/api/
 
 #### `layout`
 
-You can define the layout used to render the route. This can be either false (to disable any layout), a string or a ref/computed, if you want to make it reactive in some way. [More about layouts](/docs/guide/directory-structure/layouts).
+You can define the layout used to render the route. This can be either false (to disable any layout), a string or a ref/computed, if you want to make it reactive in some way. [More about layouts](/docs/guide/directory-structure/app/layouts).
 
 #### `layoutTransition` and `pageTransition`
 
@@ -325,7 +325,7 @@ You can set default values for these properties [in your `nuxt.config`](/docs/ap
 
 #### `middleware`
 
-You can define middleware to apply before loading this page. It will be merged with all the other middleware used in any matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function following [the global before guard pattern](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards)), or an array of strings/functions. [More about named middleware](/docs/guide/directory-structure/middleware).
+You can define middleware to apply before loading this page. It will be merged with all the other middleware used in any matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function following [the global before guard pattern](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards)), or an array of strings/functions. [More about named middleware](/docs/guide/directory-structure/app/middleware).
 
 #### `name`
 
@@ -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
 
@@ -360,7 +360,7 @@ To navigate between pages of your app, you should use the [`<NuxtLink>`](/docs/a
 
 This component is included with Nuxt and therefore you don't have to import it as you do with other components.
 
-A simple link to the `index.vue` page in your `pages` folder:
+A simple link to the `index.vue` page in your `app/pages` folder:
 
 ```vue
 <template>
@@ -399,11 +399,11 @@ function navigate(){
 
 ## Client-Only Pages
 
-You can define a page as [client only](/docs/guide/directory-structure/components#client-components) by giving it a `.client.vue` suffix. None of the content of this page will be rendered on the server.
+You can define a page as [client only](/docs/guide/directory-structure/app/components#client-components) by giving it a `.client.vue` suffix. None of the content of this page will be rendered on the server.
 
 ## Server-Only Pages
 
-You can define a page as [server only](/docs/guide/directory-structure/components#server-components) by giving it a `.server.vue` suffix. While you will be able to navigate to the page using client-side navigation, controlled by `vue-router`, it will be rendered with a server component automatically, meaning the code required to render the page will not be in your client-side bundle.
+You can define a page as [server only](/docs/guide/directory-structure/app/components#server-components) by giving it a `.server.vue` suffix. While you will be able to navigate to the page using client-side navigation, controlled by `vue-router`, it will be rendered with a server component automatically, meaning the code required to render the page will not be in your client-side bundle.
 
 ::warning
 Server-only pages must have a single root element. (HTML comments are considered elements as well.)
@@ -417,7 +417,7 @@ As your app gets bigger and more complex, your routing might require more flexib
 
 ## Multiple Pages Directories
 
-By default, all your pages should be in one `pages` directory at the root of your project.
+By default, all your pages should be in one `app/pages` directory at the root of your project.
 
 However, you can use [Nuxt Layers](/docs/getting-started/layers) to create groupings of your app's pages:
 

package/2.guide/2.directory-structure/1.app/1.plugins.md

@@ -5,7 +5,7 @@ head.title: "plugins/"
 navigation.icon: i-lucide-folder
 ---
 
-Nuxt automatically reads the files in the `plugins/` directory and loads them at the creation of the Vue application.
+Nuxt automatically reads the files in the `app/plugins/` directory and loads them at the creation of the Vue application.
 
 ::note
 All plugins inside are auto-registered, you don't need to add them to your `nuxt.config` separately.
@@ -30,7 +30,7 @@ Only files at the top level of the directory (or index files within any subdirec
 
 Only `foo.ts` and `bar/index.ts` would be registered.
 
-To add plugins in subdirectories, you can use the [`plugins`](/docs/api/nuxt-config#plugins-1) option in `nuxt.config.ts`:
+To add plugins in subdirectories, you can use the [`app/plugins`](/docs/api/nuxt-config#plugins-1) option in `nuxt.config.ts`:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -134,9 +134,9 @@ export default defineNuxtPlugin({
 
 ## Using Composables
 
-You can use [composables](/docs/guide/directory-structure/composables) as well as [utils](/docs/guide/directory-structure/utils) within Nuxt plugins:
+You can use [composables](/docs/guide/directory-structure/app/composables) as well as [utils](/docs/guide/directory-structure/app/utils) within Nuxt plugins:
 
-```ts [plugins/hello.ts]
+```ts [app/plugins/hello.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const foo = useFoo()
 })
@@ -186,7 +186,7 @@ export default defineNuxtPlugin({
 
 You can then use the helper in your components:
 
-```vue [components/Hello.vue]
+```vue [app/components/Hello.vue]
 <script setup lang="ts">
 // alternatively, you can also use it here
 const { $hello } = useNuxtApp()
@@ -200,7 +200,7 @@ const { $hello } = useNuxtApp()
 ```
 
 ::important
-Note that we highly recommend using [`composables`](/docs/guide/directory-structure/composables) instead of providing helpers to avoid polluting the global namespace and keep your main bundle entry small.
+Note that we highly recommend using [`composables`](/docs/guide/directory-structure/app/composables) instead of providing helpers to avoid polluting the global namespace and keep your main bundle entry small.
 ::
 
 ::warning
@@ -261,7 +261,7 @@ bun add -D vue-gtag-next
 
 Then create a plugin file:
 
-```ts [plugins/vue-gtag.client.ts]
+```ts [app/plugins/vue-gtag.client.ts]
 import VueGtag, { trackRouter } from 'vue-gtag-next'
 
 export default defineNuxtPlugin((nuxtApp) => {

package/2.guide/2.directory-structure/1.app/1.utils.md

@@ -5,7 +5,7 @@ description: Use the utils/ directory to auto-import your utility functions thro
 navigation.icon: i-lucide-folder
 ---
 
-The main purpose of the [`utils/` directory](/docs/guide/directory-structure/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
+The main purpose of the [`app/utils/` directory](/docs/guide/directory-structure/app/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.
 
 ## Usage
 
@@ -29,7 +29,7 @@ export default function (arr: Array<any>) {
 
 You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <p>{{ formatNumber(1234) }}</p>
 </template>
@@ -40,7 +40,7 @@ You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files
 :link-example{to="/docs/examples/features/auto-imports"}
 
 ::tip
-The way `utils/` auto-imports work and are scanned is identical to the [`composables/`](/docs/guide/directory-structure/composables) directory.
+The way `app/utils/` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/guide/directory-structure/app/composables) directory.
 ::
 
 ::important

package/2.guide/2.directory-structure/1.app/3.app-config.md

@@ -37,7 +37,7 @@ export default defineAppConfig({
 
 We can now universally access `theme` both when server-rendering the page and in the browser using [`useAppConfig`](/docs/api/composables/use-app-config) composable.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 const appConfig = useAppConfig()
 
@@ -47,7 +47,7 @@ console.log(appConfig.theme)
 
 The [`updateAppConfig`](/docs/api/utils/update-app-config) utility can be used to update the `app.config` at runtime.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup>
 const appConfig = useAppConfig() // { foo: 'bar' }
 

package/2.guide/2.directory-structure/1.app/3.app.md

@@ -6,16 +6,16 @@ navigation.icon: i-lucide-file
 ---
 
 ::tip
-If you have a `pages/` directory, the `app.vue` file is optional. Nuxt will automatically include a default `app.vue`, but you can still add your own to customize the structure and content as needed.
+If you have a `app/pages/` directory, the `app.vue` file is optional. Nuxt will automatically include a default `app.vue`, but you can still add your own to customize the structure and content as needed.
 ::
 
 ## Usage
 
 ### Minimal Usage
 
-With Nuxt, the [`pages/`](/docs/guide/directory-structure/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
+With Nuxt, the [`app/pages/`](/docs/guide/directory-structure/app/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <h1>Hello World!</h1>
 </template>
@@ -25,9 +25,9 @@ With Nuxt, the [`pages/`](/docs/guide/directory-structure/pages) directory is op
 
 ### Usage with Pages
 
-When you have a [`pages/`](/docs/guide/directory-structure/pages) directory, you need to use the [`<NuxtPage>`](/docs/api/components/nuxt-page) component to display the current page:
+When you have a [`app/pages/`](/docs/guide/directory-structure/app/pages) directory, you need to use the [`<NuxtPage>`](/docs/api/components/nuxt-page) component to display the current page:
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtPage />
 </template>
@@ -35,7 +35,7 @@ When you have a [`pages/`](/docs/guide/directory-structure/pages) directory, you
 
 You can also define the common structure of your application directly in `app.vue`. This is useful when you want to include global elements such as a header or footer:
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <header>
     Header content
@@ -51,15 +51,15 @@ You can also define the common structure of your application directly in `app.vu
 Remember that `app.vue` acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.
 ::
 
-::read-more{to="/docs/guide/directory-structure/pages"}
-Learn more about how to structure your pages using the `pages/` directory.
+::read-more{to="/docs/guide/directory-structure/app/pages"}
+Learn more about how to structure your pages using the `app/pages/` directory.
 ::
 
 ### Usage with Layouts
 
-When your application requires different layouts for different pages, you can use the `layouts/` directory with the [`<NuxtLayout>`](/docs/api/components/nuxt-layout) component. This allows you to define multiple layouts and apply them per page.
+When your application requires different layouts for different pages, you can use the `app/layouts/` directory with the [`<NuxtLayout>`](/docs/api/components/nuxt-layout) component. This allows you to define multiple layouts and apply them per page.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLayout>
     <NuxtPage />
@@ -67,6 +67,6 @@ When your application requires different layouts for different pages, you can us
 </template>
 ```
 
-::read-more{to="/docs/guide/directory-structure/layouts"}
-Learn more about how to structure your layouts using the `layouts/` directory.
+::read-more{to="/docs/guide/directory-structure/app/layouts"}
+Learn more about how to structure your layouts using the `app/layouts/` directory.
 ::

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

@@ -36,9 +36,9 @@ The module automatically loads and parses them.
 
 ## Render Content
 
-To render content pages, add a [catch-all route](/docs/guide/directory-structure/pages/#catch-all-route) using the [`<ContentRenderer>`](https://content.nuxt.com/docs/components/content-renderer) component:
+To render content pages, add a [catch-all route](/docs/guide/directory-structure/app/pages/#catch-all-route) using the [`<ContentRenderer>`](https://content.nuxt.com/docs/components/content-renderer) component:
 
-```vue [pages/[...slug\\].vue]
+```vue [app/pages/[...slug\\].vue]
 <script lang="ts" setup>
 const route = useRoute()
 const { data: page } = await useAsyncData(route.path, () => {

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

@@ -14,7 +14,7 @@ Files contained within the `public/` directory are served at the root and are no
 ---| robots.txt
 ```
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup lang="ts">
 useSeoMeta({
   ogImage: '/og-image.png'

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

@@ -31,7 +31,7 @@ export default defineEventHandler((event) => {
 
 You can now universally call this API in your pages and components:
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 const { data } = await useFetch('/api/hello')
 </script>
@@ -58,7 +58,7 @@ export default defineEventHandler(() => 'Hello World!')
 Given the example above, the `/hello` route will be accessible at <http://localhost:3000/hello>.
 
 ::note
-Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/guide/directory-structure/pages#dynamic-routes) do.
+Note that currently server routes do not support the full functionality of dynamic routes as [pages](/docs/guide/directory-structure/app/pages#dynamic-routes) do.
 ::
 
 ## Server Middleware
@@ -232,7 +232,7 @@ Alternatively, use `readValidatedBody` with a schema validator such as Zod for r
 
 You can now universally call this API using:
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup lang="ts">
 async function submit() {
   const { body } = await $fetch('/api/submit', {

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

@@ -37,7 +37,7 @@ export default function (input: string) {
 
 You can now use [auto-imported](/docs/guide/directory-structure/shared#auto-imports) utilities in your Nuxt app and `server/` directory.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup lang="ts">
 const hello = capitalize('hello')
 </script>
@@ -62,10 +62,10 @@ export default defineEventHandler((event) => {
 Only files in the `shared/utils/` and `shared/types/` directories will be auto-imported. Files nested within subdirectories of these directories will not be auto-imported unless you add these directories to `imports.dirs` and `nitro.imports.dirs`.
 
 ::tip
-The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`composables/`](/docs/guide/directory-structure/composables) and [`utils/`](/docs/guide/directory-structure/utils) directories.
+The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/guide/directory-structure/app/composables) and [`app/utils/`](/docs/guide/directory-structure/app/utils) directories.
 ::
 
-:read-more{to="/docs/guide/directory-structure/composables#how-files-are-scanned"}
+:read-more{to="/docs/guide/directory-structure/app/composables#how-files-are-scanned"}
 
 ```bash [Directory Structure]
 -| shared/

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

@@ -61,7 +61,7 @@ This feature will likely be removed in a near future.
 
 Emits `app:chunkError` hook when there is an error loading vite/webpack chunks. Default behavior is to perform a reload of the new route on navigation to a new route when a chunk fails to load.
 
-If you set this to `'automatic-immediate'` Nuxt will reload the current route immediately, instead of waiting for a navigation. This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/guide/directory-structure/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
+If you set this to `'automatic-immediate'` Nuxt will reload the current route immediately, instead of waiting for a navigation. This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/guide/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.
 
 You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.
 
@@ -220,7 +220,7 @@ export default defineNuxtConfig({
 })
 ```
 
-:read-more{to="/docs/guide/directory-structure/components#server-components"}
+:read-more{to="/docs/guide/directory-structure/app/components#server-components"}
 
 ::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
 You can follow the server components roadmap on GitHub.
@@ -423,7 +423,7 @@ export default defineNuxtConfig({
 })
 ```
 
-This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/guide/directory-structure/pages#typing-custom-metadata).
+This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/guide/directory-structure/app/pages#typing-custom-metadata).
 
 ## normalizeComponentNames
 
@@ -531,7 +531,7 @@ export default defineNuxtConfig({
 })
 ```
 
-::read-more{icon="i-simple-icons-github" color="gray" to="/docs/guide/directory-structure/components#delayed-or-lazy-hydration"}
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/guide/directory-structure/app/components#delayed-or-lazy-hydration"}
 Read more about lazy hydration.
 ::
 
@@ -575,7 +575,7 @@ export default defineNuxtConfig({
 })
 ```
 
-```ts [app.vue]
+```ts [app/app.vue]
 function something (_method: () => unknown) {
   return () => 'decorated'
 }
@@ -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/10.runtime-config.md

@@ -97,7 +97,7 @@ The behavior is different between the client-side and server-side:
 - On server-side, the entire runtime config is available, but it is read-only to avoid context sharing.
 ::
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 const config = useRuntimeConfig()
 
@@ -122,7 +122,7 @@ if (import.meta.server) {
 
 If you want to use the runtime config within any (custom) plugin, you can use [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) inside of your `defineNuxtPlugin` function.
 
-```ts [plugins/config.ts]
+```ts [app/plugins/config.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig()
 

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

@@ -41,7 +41,7 @@ Explore all available Nuxt hooks.
 
 App hooks can be mainly used by [Nuxt Plugins](/docs/guide/directory-structure/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
 
-```js [plugins/test.ts]
+```js [app/plugins/test.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   nuxtApp.hook('page:start', () => {
     /* your code goes here */