@nuxt/docs 4.0.0-alpha.4 → 4.0.0

package/1.getting-started/02.installation.md

@@ -39,23 +39,23 @@ Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.
 ::code-group{sync="pm"}
 
 ```bash [npm]
-npm create nuxt <project-name>
+npm create nuxt <project-name> -- -t v4
 ```
 
 ```bash [yarn]
-yarn create nuxt <project-name>
+yarn create nuxt <project-name> -t v4
 ```
 
 ```bash [pnpm]
-pnpm create nuxt <project-name>
+pnpm create nuxt <project-name> -t v4
 ```
 
 ```bash [bun]
-bun create nuxt <project-name>
+bun create nuxt <project-name> -t v4
 ```
 
 ```bash [deno]
-deno -A npm:create-nuxt@latest <project-name>
+deno -A npm:create-nuxt@latest <project-name> -t v4
 ```
 
 ::

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
@@ -784,7 +778,7 @@ This change should generally improve the expected behavior, but if you were expe
     query: { id },
     immediate: false
   )
-+ watch(id, execute, { once: true })
++ watch(id, () => execute(), { once: true })
 ```
 
 To opt out of this behavior:
@@ -992,6 +986,7 @@ Nuxt now generates separate TypeScript configurations for different contexts to
    * `.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.
@@ -1027,6 +1022,7 @@ However, to take advantage of improved type checking, you can opt in to the new
      "references": [
        { "path": "./.nuxt/tsconfig.app.json" },
        { "path": "./.nuxt/tsconfig.server.json" },
+       { "path": "./.nuxt/tsconfig.shared.json" },
        { "path": "./.nuxt/tsconfig.node.json" }
      ]
    }

package/2.guide/1.concepts/10.nuxt-lifecycle.md

@@ -76,17 +76,27 @@ Any redirection on the server will result in a `Location:` header being sent to
 
 :read-more{to="/docs/guide/directory-structure/middleware"}
 
-### Step 6: Setup Page and Components
+### Step 6: Render Page and Components
 
-Nuxt initializes the page and its components during this step and fetches any required data with `useFetch` and `useAsyncData`. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR.
+Nuxt renders the page and its components and fetches any required data with `useFetch` and `useAsyncData` during this step. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR.
+
+By default, Vue pauses dependency tracking during SSR for better performance.
+
+::callout{icon="i-lucide-lightbulb"}
+There is no reactivity on the server side because Vue SSR renders the app top-down as static HTML, making it impossible to go back and modify content that has already been rendered.
+::
 
 ::important
 You should avoid code that produces side effects that need cleanup in root scope of `<script setup>`. An example of such side effects is setting up timers with `setInterval`. In client-side only code we may setup a timer and then tear it down in `onBeforeUnmount` or `onUnmounted`. However, because the unmount hooks will never be called during SSR, the timers will stay around forever. To avoid this, move your side-effect code into `onMounted` instead.
 ::
 
-### Step 7: Render and Generate HTML Output
+::tip{icon="i-lucide-video" to="https://youtu.be/dZSNW07sO-A" target="_blank"}
+Watch a video from Daniel Roe explaining Server Rendering and Global State.
+::
+
+### Step 7: Generate HTML Output
 
-After all components are initialized and data is fetched, Nuxt combines the components with settings from `unhead` to generate a complete HTML document. This HTML, along with the associated data, is sent back to the client to complete the SSR process.
+After all required data is fetched and the components are rendered, Nuxt combines the rendered components with settings from `unhead` to generate a complete HTML document. This HTML, along with the associated data, is then sent back to the client to complete the SSR process.
 
 ::callout{icon="i-lucide-lightbulb"}
 After rendering the Vue application to HTML, Nuxt calls the [`app:rendered`](/docs/api/advanced/hooks#app-hooks-runtime) hook.

package/2.guide/1.concepts/8.typescript.md

@@ -92,6 +92,7 @@ When you run `nuxt dev` or `nuxt build`, Nuxt will generate multiple `tsconfig.j
 - **`.nuxt/tsconfig.app.json`** - Configuration for your application code
 - **`.nuxt/tsconfig.node.json`** - Configuration for your `nuxt.config` and modules
 - **`.nuxt/tsconfig.server.json`** - Configuration for server-side code (when applicable)
+- **`.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
 
 Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.

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/2.directory-structure/2.env.md

@@ -55,6 +55,10 @@ Since `.env` files are not used in production, you must explicitly set environme
 
 * Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.
 
+::important
+`runtimeConfig` [won't pick up environment variables that don't start with `NUXT_` in production] (https://nuxt.com/docs/guide/going-further/runtime-config#environment-variables).
+::
+
 ## Production Preview
 
 For local production preview purpose, we recommend using [`nuxt preview`](/docs/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.

package/2.guide/2.directory-structure/3.tsconfig.md

@@ -5,7 +5,7 @@ head.title: "tsconfig.json"
 navigation.icon: i-lucide-file
 ---
 
-Nuxt [automatically generates](/docs/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
+Nuxt [automatically generates](/docs/guide/concepts/typescript) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) with the resolved aliases you are using in your Nuxt project, as well as with other sensible defaults.
 
 You can benefit from this by creating a `tsconfig.json` in the root of your project with the following content:
 
@@ -19,6 +19,9 @@ You can benefit from this by creating a `tsconfig.json` in the root of your proj
     {
       "path": "./.nuxt/tsconfig.server.json"
     },
+    {
+      "path": "./.nuxt/tsconfig.shared.json"
+    },
     {
       "path": "./.nuxt/tsconfig.node.json"
     }

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

@@ -58,25 +58,6 @@ await nuxtApp.callHook('app:user:registered', {
 You can inspect all events using the **Nuxt DevTools** Hooks panel.
 ::
 
-## Augmenting Types
-
-You can augment the types of hooks provided by Nuxt.
-
-```ts
-import { HookResult } from "@nuxt/schema";
-
-declare module '#app' {
-  interface RuntimeNuxtHooks {
-    'your-nuxt-runtime-hook': () => HookResult
-  }
-  interface NuxtHooks {
-    'your-nuxt-hook': () => HookResult
-  }
-}
-
-declare module 'nitropack/types' {
-  interface NitroRuntimeHooks {
-    'your-nitro-hook': () => void;
-  }
-}
-```
+::read-more{to="/docs/guide/going-further/hooks"}
+Learn more about Nuxt's built-in hooks and how to extend them
+::

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/2.guide/3.going-further/2.hooks.md

@@ -74,6 +74,25 @@ export default defineNitroPlugin((nitroApp) => {
 Learn more about available Nitro lifecycle hooks.
 ::
 
-## Additional Hooks
+## Adding Custom Hooks
 
-Learn more about creating custom hooks in the [Events section](/docs/guide/going-further/events).
+You can define your own custom hooks support by extending Nuxt's hook interfaces.
+
+```ts
+import { HookResult } from "@nuxt/schema";
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'your-nuxt-runtime-hook': () => HookResult
+  }
+  interface NuxtHooks {
+    'your-nuxt-hook': () => HookResult
+  }
+}
+
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+    'your-nitro-hook': () => void;
+  }
+}
+```

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

@@ -559,6 +559,31 @@ export default defineNuxtModule({
 ```
 ::
 
+##### Custom Hooks
+
+Modules can also define and call their own hooks, which is a powerful pattern for making your module extensible.
+
+If you expect other modules to be able to subscribe to your module's hooks, you should call them in the `modules:done` hook. This ensures that all other modules have had a chance to be set up and register their listeners to your hook during their own `setup` function.
+
+```ts
+// my-module/module.ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export interface ModuleHooks {
+  'my-module:custom-hook': (payload: { foo: string }) => void
+}
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    // Call your hook in `modules:done`
+    nuxt.hook('modules:done', async () => {
+      const payload = { foo: 'bar' }
+      await nuxt.callHook('my-module:custom-hook', payload)
+    })
+  }
+})
+```
+
 #### Adding Templates/Virtual Files
 
 If you need to add a virtual file that can be imported into the user's app, you can use the `addTemplate` utility.

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.
@@ -159,7 +163,7 @@ const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { imm
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
 
 ::note
-If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/api/composables/use-async-data) on the client side, `data` will remain `null` within `<script setup>`.
+If you have not fetched data on the server (for example, with `server: false`), then the data _will not_ be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/api/composables/use-async-data) on the client side, `data` will remain `undefined` within `<script setup>`.
 ::
 
 ## Type
@@ -170,7 +174,7 @@ function useAsyncData<DataT, DataE>(
   options?: AsyncDataOptions<DataT>
 ): AsyncData<DataT, DataE>
 function useAsyncData<DataT, DataE>(
-  key: string | Ref<string> | ComputedRef<string>,
+  key: MaybeRefOrGetter<string>,
   handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
   options?: AsyncDataOptions<DataT>
 ): Promise<AsyncData<DataT, DataE>>
@@ -184,7 +188,7 @@ type AsyncDataOptions<DataT> = {
   default?: () => DataT | Ref<DataT> | null
   transform?: (input: DataT) => DataT | Promise<DataT>
   pick?: string[]
-  watch?: WatchSource[] | false
+  watch?: MultiWatchSources | false
   getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
 }
 
@@ -194,11 +198,11 @@ type AsyncDataRequestContext = {
 }
 
 type AsyncData<DataT, ErrorT> = {
-  data: Ref<DataT | null>
+  data: Ref<DataT | undefined>
   refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
   execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
   clear: () => void
-  error: Ref<ErrorT | null>
+  error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
 };
 

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`.
 ::
@@ -103,7 +107,7 @@ function useFetch<DataT, ErrorT>(
 ): Promise<AsyncData<DataT, ErrorT>>
 
 type UseFetchOptions<DataT> = {
-  key?: string
+  key?: MaybeRefOrGetter<string>
   method?: string
   query?: SearchParams
   params?: SearchParams
@@ -119,7 +123,8 @@ type UseFetchOptions<DataT> = {
   default?: () => DataT
   transform?: (input: DataT) => DataT | Promise<DataT>
   pick?: string[]
-  watch?: WatchSource[] | false
+  $fetch?: typeof globalThis.$fetch
+  watch?: MultiWatchSources | false
 }
 
 type AsyncDataRequestContext = {
@@ -128,11 +133,11 @@ type AsyncDataRequestContext = {
 }
 
 type AsyncData<DataT, ErrorT> = {
-  data: Ref<DataT | null>
+  data: Ref<DataT | undefined>
   refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
   execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
   clear: () => void
-  error: Ref<ErrorT | null>
+  error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
 }
 
@@ -151,7 +156,7 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 
 | Option | Type | Default | Description |
 | ---| --- | --- | --- |
-| `key` | `string` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
+| `key` | `MaybeRefOrGetter<string>` | auto-gen | Unique key for de-duplication. If not provided, generated from URL and options. |
 | `method` | `string` | `'GET'` | HTTP request method. |
 | `query` | `object` | - | Query/search params to append to the URL. Alias: `params`. Supports refs/computed. |
 | `params` | `object` | - | Alias for `query`. |
@@ -167,10 +172,10 @@ type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
 | `transform` | `(input: DataT) => DataT \| Promise<DataT>` | - | Function to transform the result after resolving. |
 | `getCachedData`| `(key, nuxtApp, ctx) => DataT \| undefined` | - | Function to return cached data. See below for default. |
 | `pick` | `string[]` | - | Only pick specified keys from the result. |
-| `watch` | `WatchSource[] \| false` | - | Array of reactive sources to watch and auto-refresh. `false` disables watching. |
+| `watch` | `MultiWatchSources \| false` | - | Array of reactive sources to watch and auto-refresh. `false` disables watching. |
 | `deep` | `boolean` | `false` | Return data in a deep ref object. |
 | `dedupe` | `'cancel' \| 'defer'` | `'cancel'` | Avoid fetching same key more than once at a time. |
-| `$fetch` | `typeof $fetch` | - | Custom $fetch implementation. |
+| `$fetch` | `typeof globalThis.$fetch` | - | Custom $fetch implementation. |
 
 ::note
 All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.
@@ -189,10 +194,10 @@ This only caches data when `experimental.payloadExtraction` in `nuxt.config` is
 
 | Name | Type | Description |
 | --- | --- |--- |
-| `data` | `Ref<DataT \| null>` | The result of the asynchronous fetch. |
+| `data` | `Ref<DataT \| undefined>` | The result of the asynchronous fetch. |
 | `refresh` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Function to manually refresh the data. By default, Nuxt waits until a `refresh` is finished before it can be executed again. |
 | `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`. |
-| `error` | `Ref<ErrorT \| null>` | Error object if the data fetching failed. |
+| `error` | `Ref<ErrorT \| undefined>` | Error object if the data fetching failed. |
 | `status` | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>` | Status of the data request. See below for possible values. |
 | `clear` | `() => void` | Resets `data` to `undefined` (or the value of `options.default()` if provided), `error` to `undefined`, set `status` to `idle`, and cancels any pending requests. |
 

package/3.api/2.composables/use-runtime-config.md

@@ -55,7 +55,7 @@ Variables that need to be accessible on the server are added directly inside `ru
 To access runtime config, we can use `useRuntimeConfig()` composable:
 
 ```ts [server/api/test.ts]
-export default defineEventHandler((event) => {
+export default defineEventHandler(async (event) => {
   const config = useRuntimeConfig(event)
 
   // Access public variables

package/3.api/4.commands/init.md

@@ -38,6 +38,8 @@ Option | Default | Description
 `--gitInit` |  | Initialize git repository
 `--shell` |  | Start shell after installation in project directory
 `--packageManager` |  | Package manager choice (npm, pnpm, yarn, bun)
+`--modules` |  | Nuxt modules to install (comma separated without spaces)
+`--no-modules` |  | Skip module installation prompt
 <!--/init-opts-->
 
 ## Environment variables

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/7.migration/2.configuration.md

@@ -164,6 +164,9 @@ Nuxt can type-check your app using [`vue-tsc`](https://github.com/vuejs/language
        {
          "path": "./.nuxt/tsconfig.server.json"
        },
+       {
+         "path": "./.nuxt/tsconfig.shared.json"
+       },
        {
          "path": "./.nuxt/tsconfig.node.json"
        }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",