@nuxt/docs 4.1.2 → 4.2.0

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

@@ -32,7 +32,147 @@ 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/4.x/guide/going-further/nightly-release-channel) guide.
+
+## Testing Nuxt 5
+
+Nuxt 5 is **currently in development**. Until the release, it is possible to test many of Nuxt 5's breaking changes from Nuxt version 4.2+.
+
+### Opting in to Nuxt 5
+
+First, upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases).
+
+Then you can set your `future.compatibilityVersion` to match Nuxt 5 behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  future: {
+    compatibilityVersion: 5,
+  },
+})
+```
+
+When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:
+
+- **Vite Environment API**: Automatically enables the new [Vite Environment API](#migration-to-vite-environment-api) for improved build configuration
+- Other Nuxt 5 improvements and changes as they become available
+
+::note
+This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 5 using `future.compatibilityVersion: 5`.
+::
+
+Breaking or significant changes will be noted below along with migration steps for backward/forward compatibility.
+
+### Migration to Vite Environment API
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+Nuxt 5 migrates to Vite 6's new [Environment API](https://vite.dev/guide/api-environment), which formalizes the concept of environments and provides better control over configuration per environment.
+
+Previously, Nuxt used separate client and server Vite configurations. Now, Nuxt uses a shared Vite configuration with environment-specific plugins that use the `applyToEnvironment()` method to target specific environments.
+
+::tip
+You can test this feature early by setting `future.compatibilityVersion: 5` (see [Testing Nuxt 5](#testing-nuxt-5)) or by enabling it explicitly with `experimental.viteEnvironmentApi: true`.
+::
+
+**Key changes:**
+
+1. **Deprecated environment-specific `extendViteConfig()`**: The `server` and `client` options in `extendViteConfig()` are deprecated and will show warnings when used.
+
+2. **Changed plugin registration**: Vite plugins registered with `addVitePlugin()` and only targeting one environment (by passing `server: false` or `client: false`) will not have their `config` or `configResolved` hooks called.
+
+3. **Shared configuration**: The `vite:extendConfig` and `vite:configResolved` hooks now work with a shared configuration rather than separate client/server configs.
+
+#### Reasons for Change
+
+The Vite Environment API provides:
+- Better consistency between development and production builds
+- More granular control over environment-specific configuration
+- Improved performance and plugin architecture
+- Support for custom environments beyond just client and server
+
+#### Migration Steps
+
+##### 1. Migrate to use Vite plugins
+
+We would recommend you use a Vite plugin instead of `extendViteConfig`, `vite:configResolved` and `vite:extendConfig`.
+
+```ts
+// Before
+extendViteConfig((config) => {
+  config.optimizeDeps.include.push('my-package')
+}, { server: false })
+
+nuxt.hook('vite:extendConfig' /* or vite:configResolved */, (config, { isClient }) => {
+  if (isClient) {
+    config.optimizeDeps.include.push('my-package')
+  }
+})
+
+// After
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    // you can set global vite configuration here
+  },
+  configResolved (config) {
+    // you can access the fully resolved vite configuration here
+  },
+  configEnvironment (name, config) {
+    // you can set environment-specific vite configuration here
+    if (name === 'client') {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('my-package')
+    }
+  },
+  applyToEnvironment (environment) {
+    return environment.name === 'client'
+  },
+}))
+```
+
+##### 2. Migrate Vite plugins to use environments
+
+Instead of using `addVitePlugin` with `server: false` or `client: false`, you can instead use the new `applyToEnvironment` hook within your plugin.
+
+```ts
+// Before
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    config.optimizeDeps.include.push('my-package')
+  },
+}), { client: false })
+
+// After
+addVitePlugin(() => ({
+  name: 'my-plugin',
+  config (config) {
+    // you can set global vite configuration here
+  },
+  configResolved (config) {
+    // you can access the fully resolved vite configuration here
+  },
+  configEnvironment (name, config) {
+    // you can set environment-specific vite configuration here
+    if (name === 'client') {
+      config.optimizeDeps ||= {}
+      config.optimizeDeps.include ||= []
+      config.optimizeDeps.include.push('my-package')
+    }
+  },
+  applyToEnvironment (environment) {
+    return environment.name === 'client'
+  },
+}))
+```
+
+::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
+Learn more about Vite's Environment API
+::
 
 ## Migrating to Nuxt 4
 
@@ -81,19 +221,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
 ```
 
 ::
@@ -110,11 +254,11 @@ Nuxt now defaults to a new directory structure, with backwards compatibility (so
 
 #### What Changed
 
-* the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
-* `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
-* `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
-* if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
-* a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
+- the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
+- `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
+- `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
+- if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
+- a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
 
 <details>
 
@@ -186,8 +330,8 @@ export default defineNuxtConfig({
   srcDir: '.',
   // This specifies the directory prefix for `router.options.ts` and `spa-loading-template.html`
   dir: {
-    app: 'app'
-  }
+    app: 'app',
+  },
 })
 ```
 
@@ -224,14 +368,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 [app/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() }),
+       },
      )
    }
    ```
@@ -260,8 +404,8 @@ Alternatively, for now, you can disable this behaviour with:
 export default defineNuxtConfig({
   experimental: {
     granularCachedData: false,
-    purgeCachedData: false
-  }
+    purgeCachedData: false,
+  },
 })
 ```
 
@@ -271,7 +415,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/4.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:
 
@@ -279,15 +423,15 @@ Now modules are loaded in the correct order:
 2. **Project modules last** (highest priority)
 
 This affects both:
-* Modules defined in the `modules` array in `nuxt.config.ts`
-* Auto-discovered modules from the `modules/` directory
+- Modules defined in the `modules` array in `nuxt.config.ts`
+- Auto-discovered modules from the `modules/` directory
 
 #### Reasons for Change
 
 This change ensures that:
-* Extended layers have lower priority than the consuming project
-* Module execution order matches the intuitive layer inheritance pattern
-* Module configuration and hooks work as expected in multi-layer setups
+- Extended layers have lower priority than the consuming project
+- Module execution order matches the intuitive layer inheritance pattern
+- Module configuration and hooks work as expected in multi-layer setups
 
 #### Migration Steps
 
@@ -303,23 +447,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/4.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.
 
@@ -380,8 +524,8 @@ Alternatively, for now, you can disable this behaviour with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    normalizeComponentNames: false
-  }
+    normalizeComponentNames: false,
+  },
 })
 ```
 
@@ -394,9 +538,9 @@ export default defineNuxtConfig({
 [Unhead](https://unhead.unjs.io/), used to generate `<head>` tags, has been updated to version 2. While mostly compatible it includes several breaking changes
 for lower-level APIs.
 
-* Removed props: `vmid`, `hid`, `children`, `body`.
-* Promise input no longer supported.
-* Tags are now sorted using Capo.js by default.
+- Removed props: `vmid`, `hid`, `children`, `body`.
+- Promise input no longer supported.
+- Tags are now sorted using Capo.js by default.
 
 #### Migration Steps
 
@@ -404,7 +548,7 @@ The above changes should have minimal impact on your app.
 
 If you have issues you should verify:
 
-* You're not using any of the removed props.
+- You're not using any of the removed props.
 
 ```diff
 useHead({
@@ -417,17 +561,17 @@ 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.
+- 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)
-  }
+  },
 })
 ```
 
@@ -444,7 +588,7 @@ If you still have issues you may revert to the v1 behavior by enabling the `head
 export default defineNuxtConfig({
   unhead: {
     legacy: true,
-  }
+  },
 })
 ```
 
@@ -483,7 +627,7 @@ Alternatively, you can revert to the previous behaviour with:
 export default defineNuxtConfig({
   experimental: {
     spaLoadingTemplateLocation: 'within',
-  }
+  },
 })
 ```
 
@@ -527,8 +671,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,
+  },
 })
 ```
 
@@ -566,8 +710,8 @@ Alternatively, you can revert to the previous behaviour with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    scanPageMeta: true
-  }
+    scanPageMeta: true,
+  },
 })
 ```
 
@@ -607,8 +751,8 @@ Alternatively, you can disable this feature with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    sharedPrerenderData: false
-  }
+    sharedPrerenderData: false,
+  },
 })
 ```
 
@@ -632,24 +776,6 @@ If you were checking if `data.value` or `error.value` were `null`, you can updat
 You can automate this step by running `npx codemod@latest nuxt/4/default-data-error-value`
 ::
 
-If you encounter any issues you can revert back to the previous behavior with:
-
-```ts twoslash [nuxt.config.ts]
-// @errors: 2353
-export default defineNuxtConfig({
-  experimental: {
-    defaults: {
-      useAsyncData: {
-        value: 'null',
-        errorValue: 'null'
-      }
-    }
-  }
-})
-```
-
-Please report an issue if you are doing this, as we do not plan to keep this as configurable.
-
 ### Removal of deprecated `boolean` values for `dedupe` option when calling `refresh` in `useAsyncData` and `useFetch`
 
 🚦 **Impact Level**: Minimal
@@ -660,7 +786,7 @@ Previously it was possible to pass `dedupe: boolean` to `refresh`. These were al
 
 ```ts twoslash [app/app.vue]
 // @errors: 2322
-const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt!' }))
+const { refresh } = await useAsyncData(() => Promise.resolve({ message: 'Hello, Nuxt!' }))
 
 async function refreshData () {
   await refresh({ dedupe: true })
@@ -748,8 +874,8 @@ Alternatively, you can temporarily revert to the previous behavior with:
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    pendingWhenIdle: true
-  }
+    pendingWhenIdle: true,
+  },
 })
 ```
 
@@ -788,8 +914,8 @@ To opt out of this behavior:
 // Or globally in your Nuxt config
 export default defineNuxtConfig({
   experimental: {
-    alwaysRunFetchOnKeyChange: true
-  }
+    alwaysRunFetchOnKeyChange: true,
+  },
 })
 ```
 
@@ -822,10 +948,10 @@ In most cases, no migration steps are required, but if you rely on the reactivit
      experimental: {
        defaults: {
          useAsyncData: {
-           deep: true
-         }
-       }
-     }
+           deep: true,
+         },
+       },
+     },
    })
    ```
 
@@ -904,10 +1030,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))
-    }
-  }
+    },
+  },
 })
 ```
 
@@ -933,9 +1059,9 @@ Finally, providing code serialization functions directly within Nuxt is not idea
 
 We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:
 
-* Moving your string interpolation logic directly into `getContents()`.
-* Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
-* Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
+- Moving your string interpolation logic directly into `getContents()`.
+- Using a custom function to handle the replacement, such as in https://github.com/nuxt-modules/color-mode/pull/240.
+- Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of _your_ project rather than Nuxt:
 
 ```diff
 + import { readFileSync } from 'node:fs'
@@ -957,7 +1083,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) => {
@@ -1002,10 +1128,10 @@ There are two approaches:
      typescript: {
        tsConfig: {
          compilerOptions: {
-           noUncheckedIndexedAccess: false
-         }
-       }
-     }
+           noUncheckedIndexedAccess: false,
+         },
+       },
+     },
    })
    ```
 
@@ -1018,11 +1144,11 @@ There are two approaches:
 Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:
 
 1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
-   * `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
-   * `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
-   * `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
-   * `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
-   * `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
+   - `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
+   - `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)  
+   - `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
+   - `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
+   - `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
 
 2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
 
@@ -1051,8 +1177,13 @@ However, to take advantage of improved type checking, you can opt in to the new
 
 1. **Update your root `tsconfig.json`** to use project references:
 
+   ::note
+   If your `tsconfig.json` currently has an `"extends": "./.nuxt/tsconfig.json"` line, **remove it** before adding the references. Project references and extends are mutually exclusive.
+   ::
+
    ```json
    {
+     // Remove "extends": "./.nuxt/tsconfig.json" if present
      "files": [],
      "references": [
        { "path": "./.nuxt/tsconfig.app.json" },
@@ -1073,9 +1204,9 @@ However, to take advantage of improved type checking, you can opt in to the new
    ```
 
 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.
+   - 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.
@@ -1090,16 +1221,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,
+         },
+       },
+     },
    })
    ```
 
@@ -1115,11 +1246,11 @@ The new configuration provides better type safety and IntelliSense for projects
 
 Four experimental features are no longer configurable in Nuxt 4:
 
-* `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
-* `experimental.configSchema` will be `true` (default since v3.3)
-* `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
-* `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
-* `vite.devBundler` is no longer configurable - it will use `vite-node` by default
+- `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
+- `experimental.configSchema` will be `true` (default since v3.3)
+- `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
+- `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
+- `vite.devBundler` is no longer configurable - it will use `vite-node` by default
 
 #### Reasons for Change
 
@@ -1127,9 +1258,9 @@ These options have been set to their current values for some time and we do not
 
 #### Migration Steps
 
-* `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
+- `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
 
-* `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
+- `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)
 
 ### Removal of Top-Level `generate` Configuration
 
@@ -1139,8 +1270,8 @@ These options have been set to their current values for some time and we do not
 
 The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:
 
-* `generate.exclude` - for excluding routes from prerendering
-* `generate.routes` - for specifying routes to prerender
+- `generate.exclude` - for excluding routes from prerendering
+- `generate.routes` - for specifying routes to prerender
 
 #### Reasons for Change
 
@@ -1195,7 +1326,7 @@ Static sites             | ✅             | ✅                | ✅
 
 The migration guide provides a step-by-step comparison of Nuxt 2 features to Nuxt 3+ features and guidance to adapt your current application.
 
-::read-more{to="/docs/migration/overview"}
+::read-more{to="/docs/4.x/migration/overview"}
 Check out the **guide to migrating from Nuxt 2 to Nuxt 3**.
 ::
 
@@ -1203,6 +1334,6 @@ Check out the **guide to migrating from Nuxt 2 to Nuxt 3**.
 
 If you prefer to progressively migrate your Nuxt 2 application to Nuxt 3, you can use Nuxt Bridge. Nuxt Bridge is a compatibility layer that allows you to use Nuxt 3+ features in Nuxt 2 with an opt-in mechanism.
 
-::read-more{to="/docs/bridge/overview"}
+::read-more{to="/docs/4.x/bridge/overview"}
 **Migrate from Nuxt 2 to Nuxt Bridge**
 ::

package/2.guide/0.index.md

@@ -7,19 +7,19 @@ 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"}
+  ::card{icon="i-lucide-folders" title="Directory Structure" to="/docs/4.x/guide/directory-structure"}
   Learn about Nuxt directory structure and what benefits each directory or file offers.
   ::
-  ::card{icon="i-lucide-star" title="Going Further" to="/docs/guide/going-further"}
+  ::card{icon="i-lucide-medal" title="Key Concepts" to="/docs/4.x/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/4.x/guide/going-further"}
   Master Nuxt with advanced concepts like experimental features, hooks, modules, and more.
   ::
-  ::card{icon="i-lucide-book-open" title="Recipes" to="/docs/guide/recipes"}
+  ::card{icon="i-lucide-book-open" title="Recipes" to="/docs/4.x/guide/recipes"}
   Find solutions to common problems and learn how to implement them in your Nuxt project.
   ::
-  ::card{icon="i-lucide-square-check" title="Best Practices" to="/docs/guide/best-practices"}
+  ::card{icon="i-lucide-square-check" title="Best Practices" to="/docs/4.x/guide/best-practices"}
   Learn about best practices when developing with Nuxt
   ::
 ::

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