@nuxt/docs-nightly 4.0.0-29206881.53f2acdc → 4.0.0-29207363.f34c6c24

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

@@ -34,76 +34,37 @@ bun x nuxt upgrade
 
 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.
 
-::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"`.
-::
-
-## Testing Nuxt 4
+## Migrating to Nuxt 4
 
-Nuxt 4 is **scheduled for release in Q2 2025**. It will include all the features currently available through `compatibilityVersion: 4`.
+Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.
 
-Until the release, it is possible to test many of Nuxt 4's breaking changes from Nuxt version 3.12+.
+First, upgrade to Nuxt 4:
 
-:video-accordion{title="Watch a video from Alexander Lichter showing how to opt in to Nuxt 4's breaking changes already" videoId="r4wFKlcJK6c"}
+::code-group{sync="pm"}
 
-### Opting in to Nuxt 4
+```bash [npm]
+npm install nuxt@^4.0.0-rc
+```
 
-First, upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases).
+```bash [yarn]
+yarn add nuxt@^4.0.0-rc
+```
 
-Then you can set your `compatibilityVersion` to match Nuxt 4 behavior:
+```bash [pnpm]
+pnpm add nuxt@^4.0.0-rc
+```
 
-::code-collapse
-```ts twoslash [nuxt.config.ts]
-export default defineNuxtConfig({
-  future: {
-    compatibilityVersion: 4,
-  },
-  // To re-enable _all_ Nuxt v3 behavior, set the following options:
-  // srcDir: '.',
-  // dir: {
-  //   app: 'app'
-  // },
-  // experimental: {
-  //   scanPageMeta: 'after-resolve',
-  //   sharedPrerenderData: false,
-  //   compileTemplate: true,
-  //   resetAsyncDataToUndefined: true,
-  //   templateUtils: true,
-  //   relativeWatchPaths: true,
-  //   normalizeComponentNames: false,
-  //   spaLoadingTemplateLocation: 'within',
-  //   parseErrorData: false,
-  //   pendingWhenIdle: true,
-  //   alwaysRunFetchOnKeyChange: true,
-  //   defaults: {
-  //     useAsyncData: {
-  //       deep: true
-  //     }
-  //   }
-  // },
-  // features: {
-  //   inlineStyles: true
-  // },
-  // unhead: {
-  //   renderSSRHeadOptions: {
-  //     omitLineBreaks: false
-  //   }
-  // }
-})
+```bash [bun]
+bun add nuxt@^4.0.0-rc
 ```
-::
 
-::note
-For now, you need to define the compatibility version in each layer that opts into Nuxt 4 behavior. This will not be required after Nuxt 4 is released.
 ::
 
-When you set your `compatibilityVersion` to `4`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v4 behavior, but you can granularly re-enable Nuxt v3 behavior when testing, following the commented out lines above. Please file issues if so, so that we can address them in Nuxt or in the ecosystem.
+After upgrading, most Nuxt 4 behaviors are now the default. However, some features can still be configured if you need to maintain backward compatibility during your migration.
 
-Breaking or significant changes will be noted here along with migration steps for backward/forward compatibility.
+The following sections detail the key changes and migrations needed when upgrading to Nuxt 4.
 
-::note
-This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 4 using `compatibilityVersion: 4`.
-::
+Breaking or significant changes are documented below along with migration steps and available configuration options.
 
 ### Migrating Using Codemods
 
@@ -303,6 +264,64 @@ export default defineNuxtConfig({
 })
 ```
 
+### Corrected Module Loading Order in Layers
+
+🚦 **Impact Level**: Minimal
+
+#### 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.
+
+Now modules are loaded in the correct order:
+
+1. **Layer modules first** (in extend order - deeper layers first)
+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
+
+#### 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
+
+#### Migration Steps
+
+**Most projects will not need changes**, as this corrects the loading order to match expected behavior.
+
+However, if your project was relying on the previous incorrect order, you may need to:
+
+1. **Review module dependencies**: Check if any modules depend on specific loading order
+2. **Adjust module configuration**: If modules were configured to work around the incorrect order
+3. **Test thoroughly**: Ensure all functionality works as expected with the corrected order
+
+Example of the new correct order:
+```ts
+// Layer: my-layer/nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['layer-module-1', 'layer-module-2']
+})
+
+// Project: nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['./my-layer'],
+  modules: ['project-module-1', 'project-module-2']
+})
+
+// Loading order (corrected):
+// 1. layer-module-1
+// 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.
+
+👉 See [PR #31507](https://github.com/nuxt/nuxt/pull/31507) and [issue #25719](https://github.com/nuxt/nuxt/issues/25719) for more details.
+
 ### Deduplication of Route Metadata
 
 🚦 **Impact Level**: Minimal
@@ -490,16 +509,6 @@ Update your custom `error.vue` to remove any additional parsing of `error.data`:
   </script>
 ```
 
-Alternatively, you can disable this change:
-
-```ts twoslash [nuxt.config.ts]
-export default defineNuxtConfig({
-  experimental: {
-    parseErrorData: false
-  },
-})
-```
-
 ### More Granular Inline Styles
 
 🚦 **Impact Level**: Moderate
@@ -697,21 +706,6 @@ If you provide a custom `default` value for `useAsyncData`, this will now be use
 
 Often users set an appropriately empty value, such as an empty array, to avoid the need to check for `null`/`undefined` when iterating over it. This should be respected when resetting/clearing the data.
 
-#### Migration Steps
-
-If you encounter any issues you can revert back to the previous behavior, for now, with:
-
-```ts twoslash [nuxt.config.ts]
-// @errors: 2353
-export default defineNuxtConfig({
-  experimental: {
-    resetAsyncDataToUndefined: true,
-  }
-})
-```
-
-Please report an issue if you are doing so, as we do not plan to keep this as configurable.
-
 ### Alignment of `pending` value in `useAsyncData` and `useFetch`
 
 🚦 **Impact Level**: Medium

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

@@ -15,12 +15,6 @@ The `shared/` directory is available in Nuxt v3.14+.
 Code in the `shared/` directory cannot import any Vue or Nitro code.
 ::
 
-::warning
-Auto-imports are not enabled by default in Nuxt v3 to prevent breaking changes in existing projects.
-
-To use these auto-imported utils and types, you must first [set `future.compatibilityVersion: 4` in your `nuxt.config.ts`](/docs/getting-started/upgrade#opting-in-to-nuxt-4).
-::
-
 :video-accordion{title="Watch a video from Vue School on sharing utils and types between app and server" videoId="nnAR-MO3q5M"}
 
 ## Usage

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

@@ -3,7 +3,7 @@ title: "Experimental Features"
 description: "Enable Nuxt experimental features to unlock new possibilities."
 ---
 
-The Nuxt experimental features can be enabled in the Nuxt configuration file.
+Nuxt includes experimental features that you can enable in your configuration file.
 
 Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/api/configuration/nuxt-config#experimental) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.
 
@@ -284,14 +284,14 @@ export default defineNuxtConfig({
 
 ## sharedPrerenderData
 
-Enabling this feature automatically shares payload *data* between pages that are prerendered. This can result
-in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and
-fetch the same data in different pages.
+Nuxt automatically shares payload *data* between pages that are prerendered. This can result in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and fetch the same data in different pages.
+
+You can disable this feature if needed.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    sharedPrerenderData: true
+    sharedPrerenderData: false
   }
 })
 ```
@@ -332,11 +332,11 @@ globalThis.Buffer = globalThis.Buffer || Buffer
 
 ## scanPageMeta
 
-This option allows exposing some route metadata defined in `definePageMeta` at build-time to modules (specifically `alias`, `name`, `path`, `redirect`, `props` and `middleware`).
+Nuxt exposing some route metadata defined in `definePageMeta` at build-time to modules (specifically `alias`, `name`, `path`, `redirect`, `props` and `middleware`).
 
 This only works with static or strings/arrays rather than variables or conditional assignment. See [original issue](https://github.com/nuxt/nuxt/issues/24770) for more information and context.
 
-It is also possible to scan page metadata only after all routes have been registered in `pages:extend`. Then another hook, `pages:resolved` will be called. To enable this behavior, set `scanPageMeta: 'after-resolve'`.
+By default page metadata is only scanned after all routes have been registered in `pages:extend`. Then another hook, `pages:resolved` will be called.
 
 You can disable this feature if it causes issues in your project.
 
@@ -427,13 +427,14 @@ This allows modules to access additional metadata from the page metadata in the
 
 ## normalizeComponentNames
 
-Ensure that auto-generated Vue component names match the full component name
-you would use to auto-import the component.
+Nuxt updates auto-generated Vue component names to match the full component name you would use to auto-import the component.
+
+If you encounter issues, you can disable this feature.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    normalizeComponentNames: true
+    normalizeComponentNames: false
   }
 })
 ```

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

@@ -39,51 +39,9 @@ There is also a `future` namespace for early opting-in to new features that will
 
 ### compatibilityVersion
 
-::important
-This configuration option is available in Nuxt v3.12+. Please note, that for now, you need to define the compatibility version in each layer that opts into Nuxt 4 behavior. This will not be required after Nuxt 4 is released.
-::
+This is used for enabling early access to Nuxt features or flags.
 
-This enables early access to Nuxt features or flags.
-
-Setting `compatibilityVersion` to `4` changes defaults throughout your
-Nuxt configuration to opt-in to Nuxt v4 behaviour, but you can granularly re-enable Nuxt v3 behaviour
-when testing (see example). Please file issues if so, so that we can
-address in Nuxt or in the ecosystem.
-
-```ts
-export default defineNuxtConfig({
-  future: {
-    compatibilityVersion: 4,
-  },
-  // To re-enable _all_ Nuxt v3 behaviour, set the following options:
-  srcDir: '.',
-  dir: {
-    app: 'app'
-  },
-  experimental: {
-    scanPageMeta: 'after-resolve',
-    sharedPrerenderData: false,
-    compileTemplate: true,
-    resetAsyncDataToUndefined: true,
-    templateUtils: true,
-    relativeWatchPaths: true,
-    normalizeComponentNames: false
-    defaults: {
-      useAsyncData: {
-        deep: true
-      }
-    }
-  },
-  features: {
-    inlineStyles: true
-  },
-  unhead: {
-    renderSSRHeadOptions: {
-      omitLineBreaks: false
-    }
-  }
-})
-```
+It is not configurable yet in Nuxt 4, but once we begin merging breaking changes for v5, it will be possible to enable it.
 
 ### typescriptBundlerResolution
 

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

@@ -142,6 +142,10 @@ const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { imm
 const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
 ```
 
+::tip
+Keyed state created using `useAsyncData` can be retrieved across your Nuxt application using [`useNuxtData`](/docs/api/composables/use-nuxt-data).
+::
+
 ## Return Values
 
 - `data`: the result of the asynchronous function that is passed in.

package/3.api/2.composables/use-fetch.md

@@ -82,6 +82,10 @@ const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
 
 When using `useFetch` with the same URL and options in multiple components, they will share the same `data`, `error` and `status` refs. This ensures consistency across components.
 
+::tip
+Keyed state created using `useFetch` can be retrieved across your Nuxt application using [`useNuxtData`](/docs/api/composables/use-nuxt-data).
+::
+
 ::warning
 `useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.
 ::

package/3.api/5.kit/9.plugins.md

@@ -214,51 +214,3 @@ export default defineNuxtPlugin({
 ```
 
 ::
-
-#### Using an EJS template to generate a plugin
-
-You can also use an EJS template to generate your plugin. Options can be passed through the `options` property and then used within the EJS template to generate the plugin content.
-
-::code-group
-
-```ts [module.ts]
-import { addPluginTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  setup (options, nuxt) {
-    const { resolve } = createResolver(import.meta.url)
-
-    addPluginTemplate({
-      src: resolve('templates/plugin.ejs'),
-      filename: 'plugin.mjs',
-      options: {
-        ssr: nuxt.options.ssr,
-      },
-    })
-  },
-})
-```
-
-```ts [templates/plugin.ejs]
-import { VueFire, useSSRInitialState } from 'vuefire'
-import { defineNuxtPlugin } from '#imports'
-
-export default defineNuxtPlugin((nuxtApp) => {
-  const firebaseApp = nuxtApp.$firebaseApp
-  nuxtApp.vueApp.use(VueFire, { firebaseApp })
-
-  <% if(options.ssr) { %>
-  if (import.meta.server) {
-    nuxtApp.payload.vuefire = useSSRInitialState(undefined, firebaseApp)
-  } else if (nuxtApp.payload?.vuefire) {
-    useSSRInitialState(nuxtApp.payload.vuefire, firebaseApp)
-  }
-  <% } %>
-})
-```
-
-::
-
-::warning
-If you set `compatibilityVersion` to `4`, Nuxt no longer uses `lodash.template` to compile templates by default. You can still enable it via the `experimental.compileTemplate` option, but support for EJS templates will be removed entirely in the next major version.
-::

package/3.api/6.nuxt-config.md

@@ -1281,42 +1281,9 @@ If set to 'production' or `true`, JS will be disabled in production mode only.
 
 ### `compatibilityVersion`
 
-Enable early access to Nuxt v4 features or flags.
+This is used for enabling early access to Nuxt features or flags.
 
-Setting `compatibilityVersion` to `4` changes defaults throughout your Nuxt configuration, but you can granularly re-enable Nuxt v3 behaviour when testing (see example). Please file issues if so, so that we can address in Nuxt or in the ecosystem.
-
-- **Type**: `number`
-- **Default:** `3`
-
-**Example**:
-```ts
-export default defineNuxtConfig({
-  future: {
-    compatibilityVersion: 4,
-  },
-  // To re-enable _all_ Nuxt v3 behaviour, set the following options:
-  srcDir: '.',
-  dir: {
-    app: 'app'
-  },
-  experimental: {
-    compileTemplate: true,
-    templateUtils: true,
-    relativeWatchPaths: true,
-    resetAsyncDataToUndefined: true,
-    defaults: {
-      useAsyncData: {
-        deep: true
-      }
-    }
-  },
-  unhead: {
-    renderSSRHeadOptions: {
-      omitLineBreaks: false
-    }
-  }
-})
-```
+It is not configurable yet in Nuxt 4, but once we begin merging breaking changes for v5, it will be possible to enable it.
 
 ### `multiApp`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.0.0-29206881.53f2acdc",
+  "version": "4.0.0-29207363.f34c6c24",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",