@nuxt/docs 4.0.3 → 4.1.1

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

@@ -28,7 +28,7 @@ pnpm create nuxt -t module my-module
 ```
 
 ```bash [bun]
-bun create nuxt -t module my-module
+bun create nuxt -- -t module my-module
 ```
 ::
 
@@ -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/6.nuxt-app.md

@@ -23,7 +23,7 @@ Jump over the `NuxtApp` interface documentation.
 
 Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
 
-Currently, the Nuxt context is only accessible in [plugins](/docs/guide/directory-structure/plugins), [Nuxt hooks](/docs/guide/going-further/hooks), [Nuxt middleware](/docs/guide/directory-structure/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
+Currently, the Nuxt context is only accessible in [plugins](/docs/guide/directory-structure/plugins), [Nuxt hooks](/docs/guide/going-further/hooks), [Nuxt middleware](/docs/guide/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
 
 If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/api/composables/use-nuxt-app#runwithcontext).
 
@@ -31,7 +31,7 @@ If a composable is called without access to the context, you may get an error st
 
 Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/api/composables/use-nuxt-app):
 
-```ts [composables/useMyComposable.ts]
+```ts [app/composables/useMyComposable.ts]
 export function useMyComposable () {
   const nuxtApp = useNuxtApp()
   // access runtime nuxt app instance

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/app/components)   - Extend the default components
+- [`app/composables/*`](/docs/guide/directory-structure/app/composables)  - Extend the default composables
+- [`app/layouts/*`](/docs/guide/directory-structure/app/layouts)  - Extend the default layouts
+- [`app/middleware/*`](/docs/guide/directory-structure/app/middleware)  - Extend the default middleware
+- [`app/pages/*`](/docs/guide/directory-structure/app/pages)        - Extend the default pages
+- [`app/plugins/*`](/docs/guide/directory-structure/plugins)        - Extend the default plugins
+- [`app/utils/*`](/docs/guide/directory-structure/app/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
 
@@ -37,7 +38,7 @@ Additionally, certain other files in the layer directory will be auto-scanned an
   })
   ```
 
-  ```vue [app.vue]
+  ```vue [app/app.vue]
     <template>
       <BaseComponent/>
     </template>
@@ -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/2.guide/4.recipes/1.custom-routing.md

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

package/2.guide/4.recipes/2.vite-plugin.md

@@ -52,7 +52,7 @@ For example, we can have a `config.yaml` that stores configuration data and impo
 greeting: "Hello, Nuxt with Vite!"
 ```
 
-```vue [components/Hello.vue]
+```vue [app/components/Hello.vue]
 <script setup>
 import config from '~/data/hello.yaml'
 </script>

package/2.guide/4.recipes/3.custom-usefetch.md

@@ -23,7 +23,7 @@ Let's pretend here that:
 - We are storing the JWT token in a session with [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils)
 - If the API responds with a `401` status code, we redirect the user to the `/login` page
 
-```ts [plugins/api.ts]
+```ts [app/plugins/api.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const { session } = useUserSession()
 
@@ -53,7 +53,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 
 With this Nuxt plugin, `$api` is exposed from `useNuxtApp()` to make API calls directly from the Vue components:
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup>
 const { $api } = useNuxtApp()
 const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
@@ -68,7 +68,7 @@ Wrapping with [`useAsyncData`](/docs/api/composables/use-async-data) **avoid dou
 
 Now that `$api` has the logic we want, let's create a `useAPI` composable to replace the usage of `useAsyncData` + `$api`:
 
-```ts [composables/useAPI.ts]
+```ts [app/composables/useAPI.ts]
 import type { UseFetchOptions } from 'nuxt/app'
 
 export function useAPI<T>(
@@ -84,7 +84,7 @@ export function useAPI<T>(
 
 Let's use the new composable and have a nice and clean component:
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup>
 const { data: modules } = await useAPI('/modules')
 </script>

package/2.guide/4.recipes/4.sessions-and-authentication.md

@@ -91,7 +91,7 @@ const { loggedIn, session, user, clear, fetch } = useUserSession()
 
 Let's create a login page with a form to submit the login data to our `/api/login` route.
 
-```vue [pages/login.vue]
+```vue [app/pages/login.vue]
 <script setup lang="ts">
 const { loggedIn, user, fetch: refreshSession } = useUserSession()
 const credentials = reactive({
@@ -143,13 +143,13 @@ export default defineEventHandler(async (event) => {
 
 ## Protect App Routes
 
-Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](https://nuxt.com/docs/guide/directory-structure/middleware) to protect the route on the client side and redirect users to the login page.
+Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](https://nuxt.com/docs/guide/directory-structure/app/middleware) to protect the route on the client side and redirect users to the login page.
 
 `nuxt-auth-utils` provides a convenient `useUserSession` composable which we'll use to check if the user is logged in, and redirect them if they are not.
 
 We'll create a middleware in the `/middleware` directory. Unlike on the server, client-side middleware is not automatically applied to all endpoints, and we'll need to specify where we want it applied.
 
-```typescript [middleware/authenticated.ts]
+```typescript [app/middleware/authenticated.ts]
 export default defineNuxtRouteMiddleware(() => {
   const { loggedIn } = useUserSession()
 
@@ -166,7 +166,7 @@ Now that we have our app middleware to protect our routes, we can use it on our
 
 We'll use [`definePageMeta`](/docs/api/utils/define-page-meta) to apply the middleware to the route that we want to protect.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 definePageMeta({
   middleware: ['authenticated'],

package/2.guide/5.best-practices/performance.md

@@ -90,7 +90,7 @@ const show = ref(false)
 
 By using the Lazy prefix you can delay loading the component code until the right moment, which can be helpful for optimizing your JavaScript bundle size.
 
-:read-more{title="Lazy loading components" to="/docs/guide/directory-structure/components#dynamic-imports"}
+:read-more{title="Lazy loading components" to="/docs/guide/directory-structure/app/components#dynamic-imports"}
 
 ### Lazy Hydration
 
@@ -106,7 +106,7 @@ It is not always necessary to hydrate (or make interactive) all the components o
 
 To optimize your app, you may want to delay the hydration of some components until they're visible, or until the browser is done with more important tasks.
 
-:read-more{title="Lazy hydration" to="/docs/guide/directory-structure/components#delayed-or-lazy-hydration"}
+:read-more{title="Lazy hydration" to="/docs/guide/directory-structure/app/components#delayed-or-lazy-hydration"}
 
 ### Fetching data
 

package/3.api/1.components/1.client-only.md

@@ -35,7 +35,7 @@ The content of the default slot will be tree-shaken out of the server build. (Th
 
 - `#fallback`: specify a content to be rendered on the server and displayed until `<ClientOnly>` is mounted in the browser.
 
-```vue [pages/example.vue]
+```vue [app/pages/example.vue]
 <template>
   <div>
     <Sidebar />
@@ -58,7 +58,7 @@ The content of the default slot will be tree-shaken out of the server build. (Th
 
 Components inside `<ClientOnly>` are rendered only after being mounted. To access the rendered elements in the DOM, you can watch a template ref:
 
-```vue [pages/example.vue]
+```vue [app/pages/example.vue]
 <script setup lang="ts">
 const nuxtWelcomeRef = useTemplateRef('nuxtWelcomeRef')
 

package/3.api/1.components/1.dev-only.md

@@ -12,7 +12,7 @@ Nuxt provides the `<DevOnly>` component to render a component only during develo
 
 The content will not be included in production builds.
 
-```vue [pages/example.vue]
+```vue [app/pages/example.vue]
 <template>
   <div>
     <Sidebar />

package/3.api/1.components/1.nuxt-client-fallback.md

@@ -18,7 +18,7 @@ Nuxt provides the `<NuxtClientFallback>` component to render its content on the
 This component is experimental and in order to use it you must enable the `experimental.clientFallback` option in your `nuxt.config`.
 ::
 
-```vue [pages/example.vue]
+```vue [app/pages/example.vue]
 <template>
   <div>
     <Sidebar />

package/3.api/1.components/12.nuxt-route-announcer.md

@@ -16,9 +16,9 @@ This component is available in Nuxt v3.12+.
 
 ## Usage
 
-Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/guide/directory-structure/app) or [`layouts/`](/docs/guide/directory-structure/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
+Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/guide/directory-structure/app) or [`app/layouts/`](/docs/guide/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtRouteAnnouncer />
   <NuxtLayout>

package/3.api/1.components/2.nuxt-page.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`pages/`](/docs/guide/directory-structure/pages) directory.
+`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/guide/directory-structure/app/pages) directory.
 
 ::note
 `<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.
@@ -63,7 +63,7 @@ Nuxt automatically resolves the `name` and `route` by scanning and rendering all
 
 For example, if you pass a key that never changes, the `<NuxtPage>` component will be rendered only once - when it is first mounted.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtPage page-key="static" />
 </template>
@@ -81,7 +81,7 @@ Don't use `$route` object here as it can cause problems with how `<NuxtPage>` re
 
 Alternatively, `pageKey` can be passed as a `key` value via [`definePageMeta`](/docs/api/utils/define-page-meta) from the `<script>` section of your Vue component in the `/pages` directory.
 
-```vue [pages/my-page.vue]
+```vue [app/pages/my-page.vue]
 <script setup lang="ts">
 definePageMeta({
   key: route => route.fullPath
@@ -95,7 +95,7 @@ definePageMeta({
 
 To get the `ref` of a page component, access it through `ref.value.pageRef`
 
-````vue [app.vue]
+````vue [app/app.vue]
 <script setup lang="ts">
 const page = ref()
 
@@ -127,7 +127,7 @@ defineExpose({
 
 For example, in the below example, the value of `foobar` will be passed to the `NuxtPage` component and then to the page components.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtPage :foobar="123" />
 </template>
@@ -135,7 +135,7 @@ For example, in the below example, the value of `foobar` will be passed to the `
 
 We can access the `foobar` prop in the page component:
 
-```vue [pages/page.vue]
+```vue [app/pages/page.vue]
 <script setup lang="ts">
 const props = defineProps<{ foobar: number }>()
 
@@ -144,11 +144,11 @@ console.log(props.foobar) // Outputs: 123
 
 If you have not defined the prop with `defineProps`, any props passed down to `NuxtPage` can still be accessed directly from the page `attrs`:
 
-```vue [pages/page.vue]
+```vue [app/pages/page.vue]
 <script setup lang="ts">
 const attrs = useAttrs()
 console.log(attrs.foobar) // Outputs: 123
 </script>
 ```
 
-:read-more{to="/docs/guide/directory-structure/pages"}
+:read-more{to="/docs/guide/directory-structure/app/pages"}

package/3.api/1.components/3.nuxt-layout.md

@@ -10,7 +10,7 @@ links:
 
 You can use `<NuxtLayout />` component to activate the `default` layout on `app.vue` or `error.vue`.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLayout>
     some page content
@@ -18,15 +18,15 @@ You can use `<NuxtLayout />` component to activate the `default` layout on `app.
 </template>
 ```
 
-:read-more{to="/docs/guide/directory-structure/layouts"}
+:read-more{to="/docs/guide/directory-structure/app/layouts"}
 
 ## Props
 
-- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/guide/directory-structure/layouts) directory.
+- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/guide/directory-structure/app/layouts) directory.
   - **type**: `string`
   - **default**: `default`
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 // layouts/custom.vue
 const layout = 'custom'
@@ -51,11 +51,11 @@ Please note the layout name is normalized to kebab-case, so if your layout file
 </template>
 ```
 
-::read-more{to="/docs/guide/directory-structure/layouts"}
+::read-more{to="/docs/guide/directory-structure/app/layouts"}
 Read more about dynamic layouts.
 ::
 
-- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/guide/directory-structure/layouts) directory.
+- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/guide/directory-structure/app/layouts) directory.
   - **type**: `string`
   - **default**: `null`
 
@@ -63,7 +63,7 @@ Read more about dynamic layouts.
 
 `NuxtLayout` also accepts any additional props that you may need to pass to the layout. These custom props are then made accessible as attributes.
 
-```vue [pages/some-page.vue]
+```vue [app/pages/some-page.vue]
 <template>
   <div>
     <NuxtLayout name="custom" title="I am a custom layout">
@@ -75,7 +75,7 @@ Read more about dynamic layouts.
 
 In the above example, the value of `title` will be available using `$attrs.title` in the template or `useAttrs().title` in `<script setup>` at custom.vue.
 
-```vue [layouts/custom.vue]
+```vue [app/layouts/custom.vue]
 <script setup lang="ts">
 const layoutCustomProps = useAttrs()
 
@@ -89,7 +89,7 @@ console.log(layoutCustomProps.title) // I am a custom layout
 
 ::code-group
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <template>
   <div>
     <NuxtLayout name="custom">
@@ -99,7 +99,7 @@ console.log(layoutCustomProps.title) // I am a custom layout
 </template>
 ```
 
-```vue [layouts/custom.vue]
+```vue [app/layouts/custom.vue]
 <template>
   <div>
     <!-- named slot -->
@@ -119,7 +119,7 @@ To get the ref of a layout component, access it through `ref.value.layoutRef`.
 
 ::code-group
 
-```vue [app.vue]
+```vue [app/app.vue]
 <script setup lang="ts">
 const layout = ref()
 
@@ -135,7 +135,7 @@ function logFoo () {
 </template>
 ```
 
-```vue [layouts/default.vue]
+```vue [app/layouts/default.vue]
 <script setup lang="ts">
 const foo = () => console.log('foo')
 defineExpose({
@@ -153,4 +153,4 @@ defineExpose({
 
 ::
 
-:read-more{to="/docs/guide/directory-structure/layouts"}
+:read-more{to="/docs/guide/directory-structure/app/layouts"}

package/3.api/1.components/4.nuxt-link.md

@@ -17,7 +17,7 @@ links:
 In this example, we use `<NuxtLink>` component to link to another page of the application.
 
 ::code-group
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <template>
   <NuxtLink to="/about">About page</NuxtLink>
 </template>
@@ -34,7 +34,7 @@ In this example, we use `<NuxtLink>` component to link to another page of the ap
 In this example, we pass the `id` param to link to the route `~/pages/posts/[id].vue`.
 
 ::code-group
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <template>
   <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
     Post 123
@@ -65,7 +65,7 @@ The `external` prop explicitly indicates that the link is external. `<NuxtLink>`
 
 For static files in the `/public` directory, such as PDFs or images, use the `external` prop to ensure the link resolves correctly.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <template>
   <NuxtLink to="/example-report.pdf" external>
     Download Report
@@ -77,7 +77,7 @@ For static files in the `/public` directory, such as PDFs or images, use the `ex
 
 When pointing to a different application on the same domain, using the `external` prop ensures the correct behavior.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <template>
   <NuxtLink to="/another-app" external>
     Go to Another App
@@ -91,7 +91,7 @@ Using the `external` prop or relying on automatic handling ensures proper naviga
 
 In this example, we use `<NuxtLink>` component to link to a website.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLink to="https://nuxtjs.org">
     Nuxt website
@@ -110,7 +110,7 @@ These defaults have no negative impact on SEO and are considered [best practice]
 
 When you need to overwrite this behavior you can use the `rel` or `noRel` props.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLink to="https://twitter.com/nuxt_js">
     Nuxt Twitter
@@ -129,7 +129,7 @@ When you need to overwrite this behavior you can use the `rel` or `noRel` props.
 
 A `noRel` prop can be used to prevent the default `rel` attribute from being added to the absolute links.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLink to="https://github.com/nuxt" no-rel>
     Nuxt GitHub
@@ -146,7 +146,7 @@ A `noRel` prop can be used to prevent the default `rel` attribute from being add
 
 Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link. Nuxt only loads the resources when the browser isn't busy and skips prefetching if your connection is offline or if you only have 2g connection.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <NuxtLink to="/about" no-prefetch>About page not pre-fetched</NuxtLink>
 <NuxtLink to="/about" :prefetch="false">About page not pre-fetched</NuxtLink>
 ```
@@ -286,7 +286,7 @@ export default defineNuxtConfig({
 
 You can overwrite `<NuxtLink>` defaults by creating your own link component using `defineNuxtLink`.
 
-```js [components/MyNuxtLink.ts]
+```js [app/components/MyNuxtLink.ts]
 export default defineNuxtLink({
   componentName: 'MyNuxtLink',
   /* see signature below for more */

package/3.api/1.components/5.nuxt-loading-indicator.md

@@ -10,9 +10,9 @@ links:
 
 ## Usage
 
-Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/guide/directory-structure/app) or [`layouts/`](/docs/guide/directory-structure/layouts).
+Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/guide/directory-structure/app) or [`app/layouts/`](/docs/guide/directory-structure/app/layouts).
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtLoadingIndicator />
   <NuxtLayout>

package/3.api/1.components/7.nuxt-welcome.md

@@ -10,7 +10,7 @@ links:
 
 It includes links to the Nuxt documentation, source code, and social media accounts.
 
-```vue [app.vue]
+```vue [app/app.vue]
 <template>
   <NuxtWelcome />
 </template>

package/3.api/2.composables/on-prehydrate.md

@@ -42,7 +42,7 @@ export function onPrehydrate(callback: string | ((el: HTMLElement) => void), key
 
 ## Example
 
-```vue twoslash [app.vue]
+```vue twoslash [app/app.vue]
 <script setup lang="ts">
 declare const window: Window
 // ---cut---

package/3.api/2.composables/use-async-data.md

@@ -16,7 +16,7 @@ Within your pages, components, and plugins you can use useAsyncData to get acces
 
 ## Usage
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 const { data, status, error, refresh, clear } = await useAsyncData(
   'mountains',
@@ -37,7 +37,7 @@ If you're using a custom useAsyncData wrapper, do not await it in the composable
 
 The built-in `watch` option allows automatically rerunning the fetcher function when any changes are detected.
 
-```vue [pages/index.vue]
+```vue [app/pages/index.vue]
 <script setup lang="ts">
 const page = ref(1)
 const { data: posts } = await useAsyncData(
@@ -57,7 +57,7 @@ const { data: posts } = await useAsyncData(
 
 You can use a computed ref, plain ref or a getter function as the key, allowing for dynamic data fetching that automatically updates when the key changes:
 
-```vue [pages/[id\\].vue]
+```vue [app/pages/[id\\].vue]
 <script setup lang="ts">
 const route = useRoute()
 const userId = computed(() => `user-${route.params.id}`)