@nuxt/docs 3.19.2 → 3.20.0

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

@@ -32,7 +32,7 @@ bun x nuxt upgrade
 
 ### Nightly Release Channel
 
-To use the latest Nuxt build and test features before their release, read about the [nightly release channel](/docs/guide/going-further/nightly-release-channel) guide.
+To use the latest Nuxt build and test features before their release, read about the [nightly release channel](/docs/3.x/guide/going-further/nightly-release-channel) guide.
 
 ::warning
 The nightly release channel `latest` tag is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now — be careful! You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.
@@ -120,19 +120,23 @@ You can run all the codemods mentioned in this guide using the following `codemo
 ::code-group
 
 ```bash [npm]
-npx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+npx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [yarn]
-yarn dlx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+yarn dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [pnpm]
-pnpm dlx codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ```bash [bun]
-bun x codemod@latest nuxt/4/migration-recipe
+# Using pinned version due to https://github.com/codemod-com/codemod/issues/1710
+bun x codemod@0.18.7 nuxt/4/migration-recipe
 ```
 
 ::
@@ -221,8 +225,8 @@ export default defineNuxtConfig({
   srcDir: '.',
   // This specifies the directory prefix for `app/router.options.ts` and `app/spa-loading-template.html`
   dir: {
-    app: 'app'
-  }
+    app: 'app',
+  },
 })
 ```
 
@@ -259,14 +263,14 @@ These changes have been made to improve memory usage and increase consistency wi
    It may be beneficial to extract any calls to `useAsyncData` that share an explicit key (and have custom options) into their own composable:
 
    ```ts [composables/useUserData.ts]
-   export function useUserData(userId: string) {
+   export function useUserData (userId: string) {
      return useAsyncData(
        `user-${userId}`,
        () => fetchUser(userId),
-       { 
+       {
          deep: true,
-         transform: (user) => ({ ...user, lastAccessed: new Date() })
-       }
+         transform: user => ({ ...user, lastAccessed: new Date() }),
+       },
      )
    }
    ```
@@ -295,8 +299,8 @@ Alternatively, for now, you can disable this behaviour with:
 export default defineNuxtConfig({
   experimental: {
     granularCachedData: false,
-    purgeCachedData: false
-  }
+    purgeCachedData: false,
+  },
 })
 ```
 
@@ -306,7 +310,7 @@ export default defineNuxtConfig({
 
 #### What Changed
 
-The order in which modules are loaded when using [Nuxt layers](/docs/guide/going-further/layers) has been corrected. Previously, modules from the project root were loaded before modules from extended layers, which was the reverse of the expected behavior.
+The order in which modules are loaded when using [Nuxt layers](/docs/3.x/guide/going-further/layers) has been corrected. Previously, modules from the project root were loaded before modules from extended layers, which was the reverse of the expected behavior.
 
 Now modules are loaded in the correct order:
 
@@ -338,23 +342,23 @@ Example of the new correct order:
 ```ts
 // Layer: my-layer/nuxt.config.ts
 export default defineNuxtConfig({
-  modules: ['layer-module-1', 'layer-module-2']
+  modules: ['layer-module-1', 'layer-module-2'],
 })
 
 // Project: nuxt.config.ts
 export default defineNuxtConfig({
   extends: ['./my-layer'],
-  modules: ['project-module-1', 'project-module-2']
+  modules: ['project-module-1', 'project-module-2'],
 })
 
 // Loading order (corrected):
 // 1. layer-module-1
-// 2. layer-module-2  
+// 2. layer-module-2
 // 3. project-module-1 (can override layer modules)
 // 4. project-module-2 (can override layer modules)
 ```
 
-If you encounter issues with module order dependencies due to needing to register a hook, consider using the [`modules:done` hook](/docs/guide/going-further/modules#custom-hooks) for modules that need to call a hook. This is run after all other modules have been loaded, which means it is safe to use.
+If you encounter issues with module order dependencies due to needing to register a hook, consider using the [`modules:done` hook](/docs/3.x/guide/going-further/modules#custom-hooks) for modules that need to call a hook. This is run after all other modules have been loaded, which means it is safe to use.
 
 👉 See [PR #31507](https://github.com/nuxt/nuxt/pull/31507) and [issue #25719](https://github.com/nuxt/nuxt/issues/25719) for more details.
 
@@ -415,8 +419,8 @@ Alternatively, for now, you can disable this behaviour with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    normalizeComponentNames: false
-  }
+    normalizeComponentNames: false,
+  },
 })
 ```
 
@@ -455,14 +459,14 @@ useHead({
 * If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.
 
 ```ts
-import { TemplateParamsPlugin, AliasSortingPlugin } from '@unhead/vue/plugins'
+import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'
 
 export default defineNuxtPlugin({
-  setup() {
+  setup () {
     const unhead = injectHead()
     unhead.use(TemplateParamsPlugin)
     unhead.use(AliasSortingPlugin)
-  }
+  },
 })
 ```
 
@@ -479,7 +483,7 @@ If you still have issues you may revert to the v1 behavior by enabling the `head
 export default defineNuxtConfig({
   unhead: {
     legacy: true,
-  }
+  },
 })
 ```
 
@@ -518,7 +522,7 @@ Alternatively, you can revert to the previous behaviour with:
 export default defineNuxtConfig({
   experimental: {
     spaLoadingTemplateLocation: 'within',
-  }
+  },
 })
 ```
 
@@ -550,7 +554,7 @@ Alternatively, you can disable this change:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    parseErrorData: false
+    parseErrorData: false,
   },
 })
 ```
@@ -572,8 +576,8 @@ This feature is fully configurable and you can revert to the previous behavior b
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   features: {
-    inlineStyles: true
-  }
+    inlineStyles: true,
+  },
 })
 ```
 
@@ -611,8 +615,8 @@ Alternatively, you can revert to the previous behaviour with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    scanPageMeta: true
-  }
+    scanPageMeta: true,
+  },
 })
 ```
 
@@ -652,8 +656,8 @@ Alternatively, you can disable this feature with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    sharedPrerenderData: false
-  }
+    sharedPrerenderData: false,
+  },
 })
 ```
 
@@ -685,10 +689,10 @@ export default defineNuxtConfig({
     defaults: {
       useAsyncData: {
         value: 'null',
-        errorValue: 'null'
-      }
-    }
-  }
+        errorValue: 'null',
+      },
+    },
+  },
 })
 ```
 
@@ -703,7 +707,8 @@ Please report an issue if you are doing this, as we do not plan to keep this as
 Previously it was possible to pass `dedupe: boolean` to `refresh`. These were aliases of `cancel` (`true`) and `defer` (`false`).
 
 ```ts twoslash [app.vue]
-const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt!' }))
+// @errors: 2322
+const { refresh } = await useAsyncData(() => Promise.resolve({ message: 'Hello, Nuxt!' }))
 
 async function refreshData () {
   await refresh({ dedupe: true })
@@ -758,7 +763,7 @@ If you encounter any issues you can revert back to the previous behavior, for no
 export default defineNuxtConfig({
   experimental: {
     resetAsyncDataToUndefined: true,
-  }
+  },
 })
 ```
 
@@ -805,8 +810,8 @@ Alternatively, you can temporarily revert to the previous behavior with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    pendingWhenIdle: true
-  }
+    pendingWhenIdle: true,
+  },
 })
 ```
 
@@ -845,8 +850,8 @@ To opt out of this behavior:
 // Or globally in your Nuxt config
 export default defineNuxtConfig({
   experimental: {
-    alwaysRunFetchOnKeyChange: true
-  }
+    alwaysRunFetchOnKeyChange: true,
+  },
 })
 ```
 
@@ -879,10 +884,10 @@ In most cases, no migration steps are required, but if you rely on the reactivit
      experimental: {
        defaults: {
          useAsyncData: {
-           deep: true
-         }
-       }
-     }
+           deep: true,
+         },
+       },
+     },
    })
    ```
 
@@ -961,10 +966,10 @@ Probably no migration is necessary but if you wish to revert to previous behavio
 ```ts
 export default defineNuxtConfig({
   hooks: {
-    'app:resolve'(app) {
+    'app:resolve' (app) {
       app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
-    }
-  }
+    },
+  },
 })
 ```
 
@@ -1014,7 +1019,7 @@ Finally, if you are using the template utilities (`serialize`, `importName`, `im
 ```ts
 import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'
 
-const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"{(.+)}"(?=,?$)/gm, r => JSON.parse(r).replace(/^{(.*)}$/, '$1'))
+const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"\{(.+)\}"(?=,?$)/gm, r => JSON.parse(r).replace(/^\{(.*)\}$/, '$1'))
 
 const importSources = (sources: string | string[], { lazy = false } = {}) => {
   return toArray(sources).map((src) => {
@@ -1059,10 +1064,10 @@ There are two approaches:
      typescript: {
        tsConfig: {
          compilerOptions: {
-           noUncheckedIndexedAccess: false
-         }
-       }
-     }
+           noUncheckedIndexedAccess: false,
+         },
+       },
+     },
    })
    ```
 
@@ -1147,16 +1152,16 @@ However, to take advantage of improved type checking, you can opt in to the new
        // Customize app/server TypeScript config
        tsConfig: {
          compilerOptions: {
-           strict: true
-         }
+           strict: true,
+         },
        },
-       // Customize build-time TypeScript config  
+       // Customize build-time TypeScript config
        nodeTsConfig: {
          compilerOptions: {
-           strict: true
-         }
-       }
-     }
+           strict: true,
+         },
+       },
+     },
    })
    ```
 

package/2.guide/0.index.md

@@ -7,12 +7,12 @@ surround: false
 ---
 
 ::card-group{class="sm:grid-cols-1"}
-  ::card{icon="i-lucide-medal" title="Key Concepts" to="/docs/guide/concepts"}
-  Discover the main concepts behind Nuxt, from auto-import, hybrid rendering to its TypeScript support.
-  ::
   ::card{icon="i-lucide-folders" title="Directory Structure" to="/docs/guide/directory-structure"}
   Learn about Nuxt directory structure and what benefits each directory or file offers.
   ::
+  ::card{icon="i-lucide-medal" title="Key Concepts" to="/docs/guide/concepts"}
+  Discover the main concepts behind Nuxt, from auto-import, hybrid rendering to its TypeScript support.
+  ::
   ::card{icon="i-lucide-star" title="Going Further" to="/docs/guide/going-further"}
   Master Nuxt with advanced concepts like experimental features, hooks, modules, and more.
   ::

package/2.guide/{2.directory-structure → 1.directory-structure}/.navigation.yml

@@ -1,3 +1,3 @@
 title: Directory Structure
 titleTemplate: '%s · Nuxt Directory Structure'
-icon: i-lucide-folders
+icon: i-vscode-icons-default-folder

package/2.guide/{2.directory-structure → 1.directory-structure}/0.nuxt.md

@@ -2,11 +2,11 @@
 title: ".nuxt"
 description: "Nuxt uses the .nuxt/ directory in development to generate your Vue application."
 head.title: ".nuxt/"
-navigation.icon: i-lucide-folder
+navigation.icon: i-vscode-icons-folder-type-temp
 ---
 
 ::important
-This directory should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing the dev build output to your repository.
+This directory should be added to your [`.gitignore`](/docs/3.x/guide/directory-structure/gitignore) file to avoid pushing the dev build output to your repository.
 ::
 
 This directory is interesting if you want to learn more about the files Nuxt generates based on your directory structure.
@@ -16,5 +16,5 @@ Nuxt also provides a Virtual File System (VFS) for modules to add templates to t
 You can explore the generated files by opening the [Nuxt DevTools](https://devtools.nuxt.com) in development mode and navigating to the **Virtual Files** tab.
 
 ::warning
-You should not touch any files inside since the whole directory will be re-created when running [`nuxt dev`](/docs/api/commands/dev).
+You should not touch any files inside since the whole directory will be re-created when running [`nuxt dev`](/docs/3.x/api/commands/dev).
 ::

package/2.guide/{2.directory-structure → 1.directory-structure}/0.output.md

@@ -2,11 +2,11 @@
 title: ".output"
 description: "Nuxt creates the .output/ directory when building your application for production."
 head.title: ".output/"
-navigation.icon: i-lucide-folder
+navigation.icon: i-vscode-icons-folder-type-package
 ---
 
 ::important
-This directory should be added to your [`.gitignore`](/docs/guide/directory-structure/gitignore) file to avoid pushing the build output to your repository.
+This directory should be added to your [`.gitignore`](/docs/3.x/guide/directory-structure/gitignore) file to avoid pushing the build output to your repository.
 ::
 
 Use this directory to deploy your Nuxt application to production.
@@ -14,5 +14,5 @@ Use this directory to deploy your Nuxt application to production.
 :read-more{to="/docs/getting-started/deployment"}
 
 ::warning
-You should not touch any files inside since the whole directory will be re-created when running [`nuxt build`](/docs/api/commands/build).
+You should not touch any files inside since the whole directory will be re-created when running [`nuxt build`](/docs/3.x/api/commands/build).
 ::

package/2.guide/{2.directory-structure → 1.directory-structure}/1.assets.md

@@ -2,15 +2,15 @@
 title: "assets"
 description: "The assets/ directory is used to add all the website's assets that the build tool will process."
 head.title: "assets/"
-navigation.icon: i-lucide-folder
+navigation.icon: i-vscode-icons-folder-type-asset
 ---
 
 The directory usually contains the following types of files:
 
 - Stylesheets (CSS, SASS, etc.)
 - Fonts
-- Images that won't be served from the [`public/`](/docs/guide/directory-structure/public) directory.
+- Images that won't be served from the [`public/`](/docs/3.x/guide/directory-structure/public) directory.
 
-If you want to serve assets from the server, we recommend taking a look at the [`public/`](/docs/guide/directory-structure/public) directory.
+If you want to serve assets from the server, we recommend taking a look at the [`public/`](/docs/3.x/guide/directory-structure/public) directory.
 
 :read-more{to="/docs/getting-started/assets"}

package/2.guide/{2.directory-structure → 1.directory-structure}/1.components.md

@@ -2,7 +2,7 @@
 title: "components"
 head.title: "components/"
 description: "The components/ directory is where you put all your Vue components."
-navigation.icon: i-lucide-folder
+navigation.icon: i-vscode-icons-folder-type-component
 ---
 
 Nuxt automatically imports any components in this directory (along with components that are registered by any modules you may be using).
@@ -54,7 +54,7 @@ export default defineNuxtConfig({
       pathPrefix: false, // [!code ++]
     },
   ],
-});
+})
 ```
 
 This registers the components using the same strategy as used in Nuxt 2. For example, `~/components/Some/MyComponent.vue` will be usable as `<MyComponent>` and not `<SomeMyComponent>`.
@@ -116,7 +116,12 @@ const show = ref(false)
   <div>
     <h1>Mountains</h1>
     <LazyMountainsList v-if="show" />
-    <button v-if="!show" @click="show = true">Show List</button>
+    <button
+      v-if="!show"
+      @click="show = true"
+    >
+      Show List
+    </button>
   </div>
 </template>
 ```
@@ -235,9 +240,10 @@ Hydrates the component based on a boolean condition.
     <LazyMyComponent :hydrate-when="isReady" />
   </div>
 </template>
+
 <script setup lang="ts">
 const isReady = ref(false)
-function myFunction() {
+function myFunction () {
   // trigger custom hydration strategy...
   isReady.value = true
 }
@@ -263,13 +269,16 @@ All delayed hydration components emit a `@hydrated` event when they are hydrated
 ```vue [pages/index.vue]
 <template>
   <div>
-    <LazyMyComponent hydrate-on-visible @hydrated="onHydrate" />
+    <LazyMyComponent
+      hydrate-on-visible
+      @hydrated="onHydrate"
+    />
   </div>
 </template>
 
 <script setup lang="ts">
-function onHydrate() {
-  console.log("Component has been hydrated!")
+function onHydrate () {
+  console.log('Component has been hydrated!')
 }
 </script>
 ```
@@ -297,7 +306,7 @@ You can also explicitly import components from `#components` if you want or need
 
 ```vue [pages/index.vue]
 <script setup lang="ts">
-import { NuxtLink, LazyMountainsList } from '#components'
+import { LazyMountainsList, NuxtLink } from '#components'
 
 const show = ref(false)
 </script>
@@ -306,7 +315,12 @@ const show = ref(false)
   <div>
     <h1>Mountains</h1>
     <LazyMountainsList v-if="show" />
-    <button v-if="!show" @click="show = true">Show List</button>
+    <button
+      v-if="!show"
+      @click="show = true"
+    >
+      Show List
+    </button>
     <NuxtLink to="/">Home</NuxtLink>
   </div>
 </template>
@@ -333,8 +347,8 @@ export default defineNuxtConfig({
     //
     // ~/components/Btn.vue => <Btn />
     // ~/components/base/Btn.vue => <BaseBtn />
-    '~/components'
-  ]
+    '~/components',
+  ],
 })
 ```
 
@@ -344,7 +358,7 @@ Any nested directories need to be added first as they are scanned in order.
 
 ## npm Packages
 
-If you want to auto-import components from an npm package, you can use [`addComponent`](/docs/api/kit/components#addcomponent) in a [local module](/docs/guide/directory-structure/modules) to register them.
+If you want to auto-import components from an npm package, you can use [`addComponent`](/docs/3.x/api/kit/components#addcomponent) in a [local module](/docs/3.x/guide/directory-structure/modules) to register them.
 
 ::code-group
 
@@ -352,7 +366,7 @@ If you want to auto-import components from an npm package, you can use [`addComp
 import { addComponent, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     // import { MyComponent as MyAutoImportedComponent } from 'my-npm-package'
     addComponent({
       name: 'MyAutoImportedComponent',
@@ -376,7 +390,7 @@ export default defineNuxtModule({
 
 ## Component Extensions
 
-By default, any file with an extension specified in the [extensions key of `nuxt.config.ts`](/docs/api/nuxt-config#extensions) is treated as a component.
+By default, any file with an extension specified in the [extensions key of `nuxt.config.ts`](/docs/3.x/api/nuxt-config#extensions) is treated as a component.
 If you need to restrict the file extensions that should be registered as components, you can use the extended form of the components directory declaration and its `extensions` key:
 
 ```ts twoslash [nuxt.config.ts]
@@ -385,8 +399,8 @@ export default defineNuxtConfig({
     {
       path: '~/components',
       extensions: ['.vue'], // [!code ++]
-    }
-  ]
+    },
+  ],
 })
 ```
 
@@ -443,8 +457,8 @@ Server components are currently experimental and in order to use them, you need
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    componentIslands: true
-  }
+    componentIslands: true,
+  },
 })
 ```
 
@@ -467,7 +481,7 @@ Now you can register server-only components with the `.server` suffix and use th
 </template>
 ```
 
-Server-only components use [`<NuxtIsland>`](/docs/api/components/nuxt-island) under the hood, meaning that `lazy` prop and `#fallback` slot are both passed down to it.
+Server-only components use [`<NuxtIsland>`](/docs/3.x/api/components/nuxt-island) under the hood, meaning that `lazy` prop and `#fallback` slot are both passed down to it.
 
 ::warning
 Server components (and islands) must have a single root element. (HTML comments are considered elements as well.)
@@ -498,7 +512,10 @@ You can partially hydrate a component by setting a `nuxt-client` attribute on th
   <div>
     <HighlightedMarkdown markdown="# Headline" />
     <!-- Counter will be loaded and hydrated client-side -->
-    <Counter nuxt-client :count="5" />
+    <Counter
+      nuxt-client
+      :count="5"
+    />
   </div>
 </template>
 ```
@@ -554,7 +571,7 @@ There are a number of components that Nuxt provides, including `<ClientOnly>` an
 
 Making Vue component libraries with automatic tree-shaking and component registration is super easy. ✨
 
-You can use the [`addComponentsDir`](/docs/api/kit/components#addcomponentsdir) method provided from the `@nuxt/kit` to register your components directory in your Nuxt module.
+You can use the [`addComponentsDir`](/docs/3.x/api/kit/components#addcomponentsdir) method provided from the `@nuxt/kit` to register your components directory in your Nuxt module.
 
 Imagine a directory structure like this:
 
@@ -573,10 +590,10 @@ Imagine a directory structure like this:
 Then in `awesome-ui/nuxt.ts` you can use the `addComponentsDir` hook:
 
 ```ts twoslash
-import { createResolver, defineNuxtModule, addComponentsDir } from '@nuxt/kit'
+import { addComponentsDir, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
-  setup() {
+  setup () {
     const resolver = createResolver(import.meta.url)
 
     // Add ./components dir to the list
@@ -592,7 +609,7 @@ That's it! Now in your project, you can import your UI library as a Nuxt module
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
-  modules: ['awesome-ui/nuxt']
+  modules: ['awesome-ui/nuxt'],
 })
 ```