@nuxt/docs 3.17.6 → 3.17.7

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

@@ -299,6 +299,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
@@ -777,7 +835,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:

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/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' {
-  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/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' {
+  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

@@ -159,7 +159,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 +170,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 +184,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
 }
 

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

@@ -103,7 +103,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 +119,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 = {
@@ -151,7 +152,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 +168,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 +190,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 `null`, set `status` to `idle`, and cancels any pending requests. |
 

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

@@ -108,5 +108,5 @@ async function addTodo () {
 ## Type
 
 ```ts
-useNuxtData<DataT = any> (key: string): { data: Ref<DataT | undefined> }
+useNuxtData<DataT = any> (key: string): { data: Ref<DataT | null> }
 ```

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/package.json

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