@nuxt/docs 4.3.0 → 4.3.1

package/1.getting-started/06.styling.md

@@ -155,7 +155,7 @@ Nuxt uses `unhead` under the hood, and you can refer to [its full documentation]
 
 If you need more advanced control, you can intercept the rendered html with a hook and modify the head programmatically.
 
-Create a plugin in `~/server/plugins/my-plugin.ts` like this:
+Create a plugin in `~~/server/plugins/my-plugin.ts` like this:
 
 <!-- TODO: figure out how to use twoslash to inject types for a different context -->
 

package/1.getting-started/15.prerendering.md

@@ -49,6 +49,14 @@ Working of the Nitro crawler:
 
 This is important to understand since pages that are not linked to a discoverable page can't be pre-rendered automatically.
 
+### Payload Extraction
+
+Nuxt generates `_payload.json` alongside HTML for:
+- Prerendered routes (at build time)
+- ISR/SWR routes (on first request)
+
+Payloads contain serialized data from `useAsyncData` and `useFetch`. Client-side navigation loads these cached payloads instead of re-fetching data. Configure dynamic routes like `pages/[...slug].vue` with route rules: `'/**': { isr: true }`.
+
 ::read-more{to="/docs/4.x/api/commands/generate#nuxt-generate"}
 Read more about the `nuxt generate` command.
 ::

package/2.directory-structure/1.server.md

@@ -43,11 +43,11 @@ const { data } = await useFetch('/api/hello')
 
 ## Server Routes
 
-Files inside the `~/server/api` are automatically prefixed with `/api` in their route.
+Files inside the `~~/server/api` are automatically prefixed with `/api` in their route.
 
 :video-accordion{title="Watch a video from Vue School on API routes" videoId="761468863" platform="vimeo"}
 
-To add server routes without `/api` prefix, put them into `~/server/routes` directory.
+To add server routes without `/api` prefix, put them into `~~/server/routes` directory.
 
 **Example:**
 
@@ -63,7 +63,7 @@ Note that currently server routes do not support the full functionality of dynam
 
 ## Server Middleware
 
-Nuxt will automatically read in any file in the `~/server/middleware` to create server middleware for your project.
+Nuxt will automatically read in any file in the `~~/server/middleware` to create server middleware for your project.
 
 Middleware handlers will run on every request before any other server route to add or check headers, log requests, or extend the event's request object.
 
@@ -87,7 +87,7 @@ export default defineEventHandler((event) => {
 
 ## Server Plugins
 
-Nuxt will automatically read any files in the `~/server/plugins` directory and register them as Nitro plugins. This allows extending Nitro's runtime behavior and hooking into lifecycle events.
+Nuxt will automatically read any files in the `~~/server/plugins` directory and register them as Nitro plugins. This allows extending Nitro's runtime behavior and hooking into lifecycle events.
 
 **Example:**
 
@@ -105,7 +105,7 @@ Server routes are powered by [h3js/h3](https://github.com/h3js/h3) which comes w
 
 :read-more{to="https://www.jsdocs.io/package/h3#package-index-functions" title="Available H3 Request Helpers" target="_blank"}
 
-You can add more helpers yourself inside the `~/server/utils` directory.
+You can add more helpers yourself inside the `~~/server/utils` directory.
 
 For example, you can define a custom handler utility that wraps the original handler and performs additional operations before returning the final response.
 
@@ -218,7 +218,7 @@ export default defineEventHandler((event) => {
 
 Catch-all routes are helpful for fallback route handling.
 
-For example, creating a file named `~/server/api/foo/[...].ts` will register a catch-all route for all requests that do not match any route handler, such as `/api/foo/bar/baz`.
+For example, creating a file named `~~/server/api/foo/[...].ts` will register a catch-all route for all requests that do not match any route handler, such as `/api/foo/bar/baz`.
 
 ```ts [server/api/foo/[...\\].ts]
 export default defineEventHandler((event) => {
@@ -228,7 +228,7 @@ export default defineEventHandler((event) => {
 })
 ```
 
-You can set a name for the catch-all route by using `~/server/api/foo/[...slug].ts` and access it via `event.context.params.slug`.
+You can set a name for the catch-all route by using `~~/server/api/foo/[...slug].ts` and access it via `event.context.params.slug`.
 
 ```ts [server/api/foo/[...slug\\].ts]
 export default defineEventHandler((event) => {

package/3.guide/1.concepts/1.rendering.md

@@ -193,6 +193,10 @@ The different properties you can use are the following:
 - `noScripts: boolean`{lang=ts} - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
 - `appMiddleware: string | string[] | Record<string, boolean>`{lang=ts} - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)
 
+::note
+Routes using `isr` or `swr` also generate `_payload.json` files alongside HTML. Client-side navigation loads these cached payloads instead of re-fetching data. Configure dynamic routes like `pages/[...slug].vue` with glob patterns: `'/**': { isr: true }`.
+::
+
 Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).
 
 ::important

package/3.guide/4.modules/3.recipes-basics.md

@@ -200,6 +200,96 @@ It is highly recommended to prefix your exports to avoid conflicts with user cod
 Note that all components, pages, composables and other files that would be normally placed in your `app/` folder need to be in `runtime/app/`. This will mean they can be type checked properly.
 ::
 
+### Add Keyed Functions
+
+Sometimes, you may need to maintain state consistency between the server and the client. Examples include Nuxt's built-in `useState` or `useAsyncData` composables. Nuxt provides a way to register such functions for automatic key injection.
+
+When a function is registered, Nuxt’s compiler automatically injects a unique key as an additional argument if the function is called with fewer than the specified number of arguments. This key remains stable between server-side rendering and client hydration.
+
+::tip
+The injected key is a hash derived from the file path and call location.
+::
+
+Use the `keyedComposables` option to register your function:
+
+```ts
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    nuxt.options.optimization.keyedComposables.push({
+      name: 'useMyState',
+      source: resolver.resolve('./runtime/composables/state'),
+      argumentLength: 2,
+    })
+  },
+})
+```
+
+The `keyedComposables` configuration accepts an array of objects with the following properties:
+
+| Property         | Type     | Description                                                                                                                |
+|------------------|----------|----------------------------------------------------------------------------------------------------------------------------|
+| `name`           | `string` | The function name. Use `'default'` for default exports (the callable name will be derived from the filename in camelCase). |
+| `source`         | `string` | Resolved path to the file where the function is defined. Supports Nuxt aliases (`~`, `@`, etc.)                            |
+| `argumentLength` | `number` | Maximum number of arguments the function accepts. When called with fewer arguments, a unique key is injected.              |
+
+For example, with `argumentLength: 2`:
+
+```ts
+useMyState() // useMyState('$HJiaryoL2y')
+useMyState('myKey') // useMyState('myKey', '$HJiaryoL2y')
+useMyState('a', 'b') // not transformed (already has 2 arguments)
+```
+
+::warning
+The key injection plugin verifies the exact resolved import source of each function call. It does not follow barrel exports. The function must be exported from the exact source file specified in the `source` property.
+
+```ts
+// ✅ Works - direct import matches the configured source
+import { useMyState } from 'my-module/runtime/composables/state'
+
+// ❌ Won't work - re-exported through a barrel file
+import { useMyState } from 'my-module/runtime/composables' // index.ts barrel
+```
+::
+
+::warning
+The function call must be statically analyzable. The compiler cannot inject keys for dynamic or indirect function calls.
+
+```ts
+import { useMyState } from 'my-module/runtime/composables/state'
+import * as composables from 'my-module/runtime/composables/state'
+
+// ✅ Works - direct function call
+useMyState()
+
+// ✅ Works - called on namespace import
+composables.useMyState()
+
+// ❌ Won't work - dynamic property access
+const name = 'useMyState'
+composables[name]()
+
+// ❌ Won't work - reassigned to a variable
+const myFn = useMyState
+myFn()
+
+// ❌ Won't work - passed as a callback
+someFunction(useMyState)
+
+// ❌ Won't work - destructured with renaming in a nested scope
+function setup () {
+  const { useMyState: localState } = composables
+  localState() // not transformed
+}
+
+// ...
+```
+::
+
 ## Add Server Routes
 
 ```ts

package/3.guide/5.recipes/4.sessions-and-authentication.md

@@ -47,7 +47,7 @@ Let's create a `/api/login` API route that will accept a POST request with the e
 import { z } from 'zod'
 
 const bodySchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   password: z.string().min(8),
 })
 

package/3.guide/6.going-further/2.hooks.md

@@ -57,7 +57,7 @@ Explore all available App hooks.
 
 These hooks are available for [server plugins](/docs/4.x/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
 
-```ts [~/server/plugins/test.ts]
+```ts [~~/server/plugins/test.ts]
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('render:html', (html, { event }) => {
     console.log('render:html', html)

package/4.api/2.composables/use-route-announcer.md

@@ -15,7 +15,7 @@ This composable is available in Nuxt v3.12+.
 ## Description
 
 A composable which observes the page title changes and updates the announcer message accordingly. Used by [`<NuxtRouteAnnouncer>`](/docs/4.x/api/components/nuxt-route-announcer) and controllable.
-It hooks into Unhead's [`dom:rendered`](https://unhead.unjs.io/docs/typescript/head/api/hooks/dom-rendered) to read the page's title and set it as the announcer message.
+It hooks into Unhead's `dom:rendered` hook to read the page's title and set it as the announcer message.
 
 ## Parameters
 

package/4.api/4.commands/add.md

@@ -4,7 +4,7 @@ description: "Scaffold an entity into your Nuxt application."
 links:
   - label: Source
     icon: i-simple-icons-github
-    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/add.ts
+    to: https://github.com/nuxt/cli/blob/main/packages/nuxi/src/commands/add-template.ts
     size: xs
 ---
 

package/4.api/5.kit/11.nitro.md

@@ -301,6 +301,10 @@ function addPrerenderRoutes (routes: string | string[]): void
 
 Add imports to the server. It makes your imports available in Nitro without the need to import them manually.
 
+::warning
+If you want to provide a utility that works in both server and client contexts and is usable in the [`shared/`](/docs/4.x/directory-structure/shared) directory, the function must be imported from the same source file for both [`addImports`](/docs/4.x/api/kit/autoimports#addimports) and `addServerImports` and should have identical signature. That source file should not import anything context-specific (i.e., Nitro context, Nuxt app context) or else it might cause errors during type-checking.
+::
+
 ### Usage
 
 ```ts twoslash
@@ -422,10 +426,10 @@ export default defineEventHandler(() => {
 ## `addServerScanDir`
 
 Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered
-just like the `~/server` folder is.
+just like the `~~/server` folder is.
 
 ::note
-Only `~/server/api`, `~/server/routes`, `~/server/middleware`, and `~/server/utils` are scanned.
+Only `~~/server/api`, `~~/server/routes`, `~~/server/middleware`, and `~~/server/utils` are scanned.
 ::
 
 ### Usage

package/4.api/5.kit/4.autoimports.md

@@ -24,7 +24,11 @@ Watch Vue School video about Auto-imports Nuxt Kit utilities.
 
 ## `addImports`
 
-Add imports to the Nuxt application. It makes your imports available in the Nuxt application without the need to import them manually.
+Add imports to the Nuxt application. It makes your imports available in the Nuxt app context without the need to import them manually.
+
+::tip
+To add imports for the Nitro server context, refer to the [`addServerImports`](/docs/4.x/api/kit/nitro#addserverimports) function.
+::
 
 ### Usage
 

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

@@ -13,12 +13,13 @@ You can improve your DX by defining additional aliases to access custom director
 - **Default**
 ```json
 {
-  "~": "/<srcDir>",
-  "@": "/<srcDir>",
+  "~": "/<rootDir>/app",
+  "@": "/<rootDir>/app",
   "~~": "/<rootDir>",
   "@@": "/<rootDir>",
   "#shared": "/<rootDir>/shared",
-  "assets": "/<srcDir>/assets",
+  "#server": "/<rootDir>/server",
+  "assets": "/<rootDir>/app/assets",
   "public": "/<rootDir>/public",
   "#build": "/<rootDir>/.nuxt",
   "#internal/nuxt/paths": "/<rootDir>/.nuxt/paths.mjs"
@@ -372,7 +373,7 @@ export default defineNuxtConfig({
   build: {
     templates: [
       {
-        src: '~/modules/support/plugin.js', // `src` can be absolute or relative
+        src: '~~/modules/support/plugin.js', // `src` can be absolute or relative
         dst: 'support.js', // `dst` is relative to project `.nuxt` dir
       },
     ],
@@ -880,7 +881,7 @@ Defaults to 'silent' when running in CI or when a TTY is not available. This opt
 Modules are Nuxt extensions which can extend its core functionality and add endless integrations.
 
 Each module is either a string (which can refer to a package, or be a path to a file), a tuple with the module as first string and the options as a second object, or an inline module function.
-Nuxt tries to resolve each item in the modules array using node require path (in `node_modules`) and then will be resolved from project `srcDir` if `~` alias is used.
+Nuxt tries to resolve each item in the modules array using node require path (in `node_modules`) and then will be resolved from project `rootDir` if `~~` alias is used.
 
 - **Type**: `array`
 
@@ -895,8 +896,8 @@ export default defineNuxtConfig({
   modules: [
   // Using package name
     '@nuxt/scripts',
-    // Relative to your project srcDir
-    '~/custom-modules/awesome.js',
+    // Relative to your project rootDir
+    '~~/custom-modules/awesome.js',
     // Providing options
     ['@nuxtjs/google-analytics', { ua: 'X1234567' }],
     // Inline definition
@@ -1013,8 +1014,12 @@ Options passed directly to the transformer from `unctx` that preserves async con
 
 Functions to inject a key for.
 
-As long as the number of arguments passed to the function is less than `argumentLength`, an additional magic string will be injected that can be used to deduplicate requests between server and client. You will need to take steps to handle this additional key.
-The key will be unique based on the location of the function being invoked within the file.
+As long as the number of arguments passed to the function is less than `argumentLength`, an additional magic string will be injected as the last argument. This key is stable between SSR and client-side hydration. You will need to take steps to handle this additional key.
+The key is unique based on the location of the function being invoked within the file.
+
+::read-more{to="/docs/4.x/guide/modules/recipes-basics#add-keyed-functions"}
+Learn more about keyed functions.
+::
 
 - **Type**: `array`
 - **Default**
@@ -1022,31 +1027,38 @@ The key will be unique based on the location of the function being invoked withi
 [
   {
     "name": "callOnce",
-    "argumentLength": 3
+    "argumentLength": 3,
+    "source": "#app/composables/once"
   },
   {
     "name": "defineNuxtComponent",
-    "argumentLength": 2
+    "argumentLength": 2,
+    "source": "#app/composables/component"
   },
   {
     "name": "useState",
-    "argumentLength": 2
+    "argumentLength": 2,
+    "source": "#app/composables/state"
   },
   {
     "name": "useFetch",
-    "argumentLength": 3
+    "argumentLength": 3,
+    "source": "#app/composables/fetch"
   },
   {
     "name": "useAsyncData",
-    "argumentLength": 3
+    "argumentLength": 3,
+    "source": "#app/composables/asyncData"
   },
   {
     "name": "useLazyAsyncData",
-    "argumentLength": 3
+    "argumentLength": 3,
+    "source": "#app/composables/asyncData"
   },
   {
     "name": "useLazyFetch",
-    "argumentLength": 3
+    "argumentLength": 3,
+    "source": "#app/composables/fetch"
   }
 ]
 ```
@@ -1297,7 +1309,7 @@ Define the server directory of your Nuxt application, where Nitro routes, middle
 If a relative path is specified, it will be relative to your `rootDir`.
 
 - **Type**: `string`
-- **Default:** `"/<srcDir>/server"`
+- **Default:** `"/<rootDir>/server"`
 
 ## serverHandlers
 
@@ -1318,7 +1330,7 @@ Each handler accepts the following options:
 ```ts
 export default defineNuxtConfig({
   serverHandlers: [
-    { route: '/path/foo/**:name', handler: '~/server/foohandler.ts' },
+    { route: '/path/foo/**:name', handler: '#server/foohandler.ts' },
   ],
 })
 ```
@@ -1408,22 +1420,27 @@ export default defineNuxtConfig({
   srcDir: 'app/',
 })
 ```
+
 This expects the following folder structure:
 ```bash
 -| app/
 ---| assets/
 ---| components/
+---| composables/
 ---| layouts/
 ---| middleware/
 ---| pages/
 ---| plugins/
+---| utils/
 ---| app.config.ts
 ---| app.vue
 ---| error.vue
 -| server/
+-| shared/
 -| public/
 -| modules/
--| nuxt.config.js
+-| layers/
+-| nuxt.config.ts
 -| package.json
 ```
 
@@ -1692,7 +1709,7 @@ Please note that not all vite options are supported in Nuxt.
 ### `root`
 
 - **Type**: `string`
-- **Default:** `"/<srcDir>"`
+- **Default:** `"/<rootDir>"`
 
 ### `server`
 
@@ -1705,7 +1722,7 @@ Please note that not all vite options are supported in Nuxt.
 ```json
 [
   "/<rootDir>/.nuxt",
-  "/<srcDir>",
+  "/<rootDir>/app",
   "/<rootDir>",
   "/<workspaceDir>"
 ]

package/5.community/6.roadmap.md

@@ -61,15 +61,15 @@ We commit to support each major version of Nuxt for a minimum of six months afte
 
 The current active version of [Nuxt](https://nuxt.com) is **v4** which is available as `nuxt` on npm with the `latest` tag.
 
-Nuxt 3 will continue to receive maintenance updates (both bug fixes and backports of features from Nuxt 4) until the end of January 2026.
+Nuxt 3 will continue to receive maintenance updates (bug fixes and security patches) until the end of July 2026.
 
 Each active version has its own nightly releases which are generated automatically. For more about enabling the Nuxt nightly release channel, see [the nightly release channel docs](/docs/4.x/guide/going-further/nightly-release-channel).
 
 | Release               |                                                                                                                                                                                                                                                    | Initial release     | End Of Life                | Docs                                                              |
 |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|----------------------------|-------------------------------------------------------------------|
-| **5.x** (scheduled)   |                                                                                                                                                                                                                                                    | Q4 2025 (estimated) | TBA                        |                                                              |
+| **5.x** (scheduled)   |                                                                                                                                                                                                                                                    | Q1 2026 (estimated) | TBA                        |                                                              |
 | **4.x** (stable)      | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt latest version" src="https://img.shields.io/npm/v/nuxt.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" class="not-prose h-5 w-auto" :zoom="false"></a> | 2025-07-16          | 6 months after 5.x release | [nuxt.com](/docs/4.x/getting-started/introduction)                |
-| **3.x** (maintenance) | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 3.x version" src="https://img.shields.io/npm/v/nuxt/3x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" class="not-prose h-5 w-auto" :zoom="false"></a> | 2022-11-16          | 2026-01-31                 | [nuxt.com](/docs/3.x/getting-started/introduction)                |
+| **3.x** (maintenance) | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 3.x version" src="https://img.shields.io/npm/v/nuxt/3x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" class="not-prose h-5 w-auto" :zoom="false"></a> | 2022-11-16          | 2026-07-31                 | [nuxt.com](/docs/3.x/getting-started/introduction)                |
 | **2.x** (unsupported) | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 2.x version" src="https://img.shields.io/npm/v/nuxt/2x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" class="not-prose h-5 w-auto" :zoom="false"></a> | 2018-09-21          | 2024-06-30                 | [v2.nuxt.com](https://v2.nuxt.com/docs/get-started/installation/) |
 | **1.x** (unsupported) | <a href="https://www.npmjs.com/package/nuxt?activeTab=versions"><img alt="Nuxt 1.x version" src="https://img.shields.io/npm/v/nuxt/1x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" class="not-prose h-5 w-auto" :zoom="false"></a> | 2018-01-08          | 2019-09-21                 | &nbsp;                                                            |
 

package/7.migration/11.server.md

@@ -10,7 +10,7 @@ In a built Nuxt 3 application, there is no runtime Nuxt dependency. That means y
 ## Steps
 
 1. Remove the `render` key in your `nuxt.config`.
-2. Any files in `~/server/api` and `~/server/middleware` will be automatically registered; you can remove them from your `serverMiddleware` array.
+2. Any files in `~~/server/api` and `~~/server/middleware` will be automatically registered; you can remove them from your `serverMiddleware` array.
 3. Update any other items in your `serverMiddleware` array to point to files or npm packages directly, rather than using inline functions.
 
 :read-more{to="/docs/4.x/directory-structure/server"}

package/package.json

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