@nuxt/docs-nightly 4.4.0-29550724.be97f20e → 4.4.0-29551604.0a8a57da

package/1.getting-started/17.testing.md

@@ -300,6 +300,10 @@ it('can also mount an app', async () => {
 })
 ```
 
+The options object accepts `@vue/test-utils` mount options and the following properties:
+
+  - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+
 #### `renderSuspended`
 
 `renderSuspended` allows you to render any Vue component within the Nuxt environment using `@testing-library/vue`, allowing async setup and access to injections from your Nuxt plugins.
@@ -352,14 +356,18 @@ it('can also render an app', async () => {
 })
 ```
 
+The options object accepts `@testing-library/vue` render options and the following properties:
+
+  - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+
 #### `mockNuxtImport`
 
-`mockNuxtImport` allows you to mock Nuxt's auto import functionality. For example, to mock `useStorage`, you can do so like this:
+`mockNuxtImport` allows you to mock Nuxt's auto import functionality. For example, to mock `useState`, you can do so like this:
 
 ```ts twoslash
 import { mockNuxtImport } from '@nuxt/test-utils/runtime'
 
-mockNuxtImport('useStorage', () => {
+mockNuxtImport('useState', () => {
   return () => {
     return { value: 'mocked storage' }
   }
@@ -368,6 +376,27 @@ mockNuxtImport('useStorage', () => {
 // your tests here
 ```
 
+You can explicitly type the mock for type safety, and use the original implementation passed to the factory function when mocking complex functionality.
+
+```ts twoslash [test/nuxt/import.test.ts]
+import { mockNuxtImport } from '@nuxt/test-utils/runtime'
+
+mockNuxtImport<typeof useState>('useState', (original) => {
+  return (...args) => {
+    return { ...original('some-key'), value: 'mocked state' }
+  }
+})
+
+// or specify the target to mock
+mockNuxtImport(useState, (original) => {
+  return (...args) => {
+    return { ...original('some-key'), value: 'mocked state' }
+  }
+})
+
+// your tests here
+```
+
 ::note
 `mockNuxtImport` can only be used once per mocked import per test file. It is actually a macro that gets transformed to `vi.mock` and `vi.mock` is hoisted, as described [in the Vitest docs](https://vitest.dev/api/vi#vi-mock).
 ::
@@ -378,24 +407,43 @@ If you need to mock a Nuxt import and provide different implementations between
 import { vi } from 'vitest'
 import { mockNuxtImport } from '@nuxt/test-utils/runtime'
 
-const { useStorageMock } = vi.hoisted(() => {
+const { useStateMock } = vi.hoisted(() => {
   return {
-    useStorageMock: vi.fn(() => {
+    useStateMock: vi.fn(() => {
       return { value: 'mocked storage' }
     }),
   }
 })
 
-mockNuxtImport('useStorage', () => {
-  return useStorageMock
+mockNuxtImport('useState', () => {
+  return useStateMock
 })
 
 // Then, inside a test
-useStorageMock.mockImplementation(() => {
+useStateMock.mockImplementation(() => {
   return { value: 'something else' }
 })
 ```
 
+If you need to mock behavior only inside a test, you can also use the following approach.
+
+```ts twoslash
+import { beforeEach, vi } from 'vitest'
+import { mockNuxtImport } from '@nuxt/test-utils/runtime'
+
+mockNuxtImport(useRoute, original => vi.fn(original))
+
+beforeEach(() => {
+  vi.resetAllMocks()
+})
+
+// Then, inside a test
+const useRouteOriginal = vi.mocked(useRoute).getMockImplementation()!
+vi.mocked(useRoute).mockImplementation(
+  (...args) => ({ ...useRouteOriginal(...args), path: '/mocked' }),
+)
+```
+
 #### `mockComponent`
 
 `mockComponent` allows you to mock Nuxt's component.
@@ -477,6 +525,12 @@ registerEndpoint('/test/', {
 })
 ```
 
+This object accepts the following properties:
+
+- `handler`: the event handler function
+- `method`: (optional) HTTP method to match (e.g., 'GET', 'POST')
+- `once`: (optional) if true, the handler will only be used for the first matching request and then automatically removed
+
 > **Note**: If your requests in a component go to an external API, you can use `baseURL` and then make it empty using [Nuxt Environment Override Config](/docs/4.x/getting-started/configuration#environment-overrides) (`$test`) so all your requests will go to Nitro server.
 
 #### Conflict with End-To-End Testing
@@ -490,7 +544,7 @@ If you would like to use both the end-to-end and unit testing functionality of `
 ```ts twoslash
 import { mockNuxtImport } from '@nuxt/test-utils/runtime'
 
-mockNuxtImport('useStorage', () => {
+mockNuxtImport('useState', () => {
   return () => {
     return { value: 'mocked storage' }
   }

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

@@ -61,6 +61,7 @@ When you set your `future.compatibilityVersion` to `5`, defaults throughout your
 - **Vite Environment API**: Automatically enables the new [Vite Environment API](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for improved build configuration
 - **Normalized Page Names**: Page component names will [match their route names](/docs/4.x/getting-started/upgrade#normalized-page-component-names) for consistent `<KeepAlive>` behavior
 - **`clearNuxtState` resets to defaults**: `clearNuxtState` will [reset state to its initial value](/docs/4.x/getting-started/upgrade#respect-defaults-when-clearing-usestate) instead of setting it to `undefined`
+- **Non-async `callHook`**: [`callHook` may return `void`](/docs/4.x/getting-started/upgrade#non-async-callhook) instead of always returning a `Promise`
 - Other Nuxt 5 improvements and changes as they become available
 
 ::note
@@ -180,6 +181,52 @@ addVitePlugin(() => ({
 Learn more about Vite's Environment API
 ::
 
+### Non-Async `callHook`
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+With the upgrade to [hookable v6](https://github.com/unjs/hookable), `callHook` may now return `void` instead of always returning `Promise<void>`. This is a significant performance improvement that avoids unnecessary `Promise` allocations when there are no registered hooks or all hooks are synchronous.
+
+By default (with `compatibilityVersion: 4`), Nuxt wraps `callHook` with `Promise.resolve()` so that existing `.then()` and `.catch()` chaining continues to work. With `compatibilityVersion: 5`, this wrapper is removed.
+
+::tip
+This affects both build-time Nuxt hooks (used by Nuxt modules) and runtime Nuxt hooks (which you might use in your application code).
+::
+
+#### Reasons for Change
+
+Hookable v6's `callHook` is 20-40x faster because it avoids creating a `Promise` when one is not needed. This benefits applications with many hook call sites.
+
+#### Migration Steps
+
+If you or your modules use `callHook` with `.then()` or `.catch()` chaining, switch to `await`:
+
+```diff
+- nuxtApp.callHook('my:hook', data).then(() => { ... })
++ await nuxtApp.callHook('my:hook', data)
+```
+
+```diff
+- nuxtApp.hooks.callHook('my:hook', data).catch(err => { ... })
++ try { await nuxtApp.hooks.callHook('my:hook', data) } catch (err) { ... }
+```
+
+::tip
+You can test this feature early by setting `future.compatibilityVersion: 5` (see [Testing Nuxt 5](/docs/4.x/getting-started/upgrade#testing-nuxt-5)) or by enabling it explicitly with `experimental.asyncCallHook: false`.
+::
+
+Alternatively, you can ensure `callHook` always returns a `Promise` with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    asyncCallHook: true,
+  },
+})
+```
+
 ## Migrating to Nuxt 4
 
 Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.

package/2.directory-structure/1.app/1.layouts.md

@@ -122,7 +122,7 @@ File | Layout Name
 
 You can also use the [`setPageLayout`](/docs/4.x/api/utils/set-page-layout) helper to change the layout dynamically:
 
-```vue twoslash
+```vue twoslash [app/pages/index.vue]
 <script setup lang="ts">
 declare module 'nuxt/app' {
   interface NuxtLayouts {

package/3.guide/2.best-practices/hydration.md

@@ -6,32 +6,32 @@ description: Why fixing hydration issues is important
 
 When developing, you may face hydration issues. Don't ignore those warnings.
 
-# Why is it important to fix them?
+## Why is it important to fix them?
 
 Hydration mismatches are not just warnings - they are indicators of serious problems that can break your application:
 
-## Performance Impact
+### Performance Impact
 
 - **Increased time to interactive**: Hydration errors force Vue to re-render the entire component tree, which will increase the time for your Nuxt app to become interactive
 - **Poor user experience**: Users may see content flashing or unexpected layout shifts
 
-## Functionality Issues
+### Functionality Issues
 
 - **Broken interactivity**: Event listeners may not attach properly, leaving buttons and forms non-functional
 - **State inconsistencies**: Application state can become out of sync between what the user sees and what the application thinks is rendered
 - **SEO problems**: Search engines may index different content than what users actually see
 
-# How to detect them
+## How to detect them
 
-## Development Console Warnings
+### Development Console Warnings
 
 Vue will log hydration mismatch warnings in the browser console during development:
 
 ![Screenshot of Vue hydration mismatch warning in the browser console](/assets/docs/best-practices/vue-console-hydration.png)
 
-# Common reasons
+## Common reasons
 
-## Browser-only APIs in Server Context
+### Browser-only APIs in Server Context
 
 **Problem**: Using browser-specific APIs during server-side rendering.
 
@@ -60,7 +60,7 @@ const userTheme = useCookie('theme', { default: () => 'light' })
 </script>
 ```
 
-## Inconsistent Data
+### Inconsistent Data
 
 **Problem**: Different data between server and client.
 
@@ -82,7 +82,7 @@ const state = useState('random', () => Math.random())
 </script>
 ```
 
-## Conditional Rendering Based on Client State
+### Conditional Rendering Based on Client State
 
 **Problem**: Using client-only conditions during SSR.
 
@@ -105,7 +105,7 @@ const state = useState('random', () => Math.random())
 </template>
 ```
 
-## Third-party Libraries with Side Effects
+### Third-party Libraries with Side Effects
 
 **Problem**: Libraries that modify the DOM or have browser dependencies (this happens a LOT with tag managers).
 
@@ -129,7 +129,7 @@ onMounted(async () => {
 </script>
 ```
 
-## Dynamic Content Based on Time
+### Dynamic Content Based on Time
 
 **Problem**: Content that changes based on current time.
 

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

@@ -238,12 +238,19 @@ export default defineNuxtConfig({
 
 ## payloadExtraction
 
-Enables extraction of payloads of pages generated with `nuxt generate`.
+Controls how payload data is delivered for prerendered and cached (ISR/SWR) pages.
+
+- `'client'` - Payload is inlined in HTML for the initial server render, and extracted to `_payload.json` files for client-side navigation. This avoids a separate network request on initial load while still enabling efficient client-side navigation.
+- `true` - Payload is extracted to a separate `_payload.json` file for both the initial server render and client-side navigation.
+- `false` - Payload extraction is disabled entirely. Payload is always inlined in HTML and no `_payload.json` files are generated.
+
+The default is `true`, or `'client'` when `compatibilityVersion: 5` is set.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true,
+    // Inline payload in HTML, extract for client-side navigation only
+    payloadExtraction: 'client',
   },
 })
 ```
@@ -253,7 +260,7 @@ Payload extraction also works for routes using ISR (Incremental Static Regenerat
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true,
+    payloadExtraction: 'client',
   },
   routeRules: {
     // Payload files will be generated for these cached routes
@@ -766,7 +773,9 @@ export default defineNuxtConfig({
 
 ## decorators
 
-This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
+This option enables decorator syntax across your entire Nuxt/Nitro app.
+
+When using the Vite builder (default), decorators are lowered via [Babel](https://babeljs.io/) using [`@babel/plugin-proposal-decorators`](https://babeljs.io/docs/babel-plugin-proposal-decorators). When using the webpack or rspack builders, decorators are lowered via [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
 
 For a long time, TypeScript has had support for decorators via `compilerOptions.experimentalDecorators`. This implementation predated the TC39 standardization process. Now, decorators are a [Stage 3 Proposal](https://github.com/tc39/proposal-decorators), and supported without special configuration in TS 5.0+ (see https://github.com/microsoft/TypeScript/pull/52582 and https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).
 
@@ -786,6 +795,24 @@ export default defineNuxtConfig({
 })
 ```
 
+When using the Vite builder or the Nitro server build, you will need to install additional Babel packages as dev dependencies:
+
+::code-group
+```bash [npm]
+npm install -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+```bash [pnpm]
+pnpm add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+```bash [yarn]
+yarn add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+::
+
+::tip
+Nuxt will prompt you to install these automatically if they are not already present.
+::
+
 ```ts [app/app.vue]
 function something (_method: () => unknown) {
   return () => 'decorated'

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

@@ -161,6 +161,7 @@ type AsyncDataRequestContext = {
 
 type AsyncData<DataT, ErrorT> = {
   data: Ref<DataT | undefined>
+  pending: Ref<boolean>
   refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
   execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
   clear: () => void
@@ -229,6 +230,7 @@ This only caches data when `experimental.payloadExtraction` in `nuxt.config` is
 | `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`.                                                                                                                                              |
 | `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.                                                                                                        |
+| `pending` | `Ref<boolean>`                                      | Boolean flag indicating whether the current request is in progress.                                                                                                |
 | `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. |
 
 ### Status values

package/4.api/2.composables/use-lazy-fetch.md

@@ -76,6 +76,7 @@ Returns the same `AsyncData` object as [`useFetch`](/docs/4.x/api/composables/us
 | `execute` | `(opts?: AsyncDataExecuteOptions) => Promise<void>` | Alias for `refresh`.                                                                                             |
 | `error`   | `Ref<ErrorT \| undefined>`                          | Error object if the data fetching failed.                                                                        |
 | `status`  | `Ref<'idle' \| 'pending' \| 'success' \| 'error'>`  | Status of the data request.                                                                                      |
+| `pending` | `Ref<boolean>`                                      | Boolean flag indicating whether the current request is in progress.                                              |
 | `clear`   | `() => void`                                        | Resets `data` to `undefined`, `error` to `undefined`, sets `status` to `idle`, and cancels any pending requests. |
 
 :read-more{to="/docs/4.x/api/composables/use-fetch#return-values"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.4.0-29550724.be97f20e",
+  "version": "4.4.0-29551604.0a8a57da",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",