@nuxt/docs 3.21.0 → 3.21.1

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/3.x/api/commands/generate#nuxt-generate"}
 Read more about the `nuxt generate` command.
 ::

package/3.guide/0.index.md

@@ -13,9 +13,6 @@ surround: false
   ::card{icon="i-lucide-square-check" title="Best Practices" to="/docs/3.x/guide/best-practices"}
   Learn about best practices when developing with Nuxt.
   ::
-  ::card{icon="i-lucide-bot" title="Working with AI" to="/docs/4.x/guide/ai"}
-  Integrate AI tools into your Nuxt workflow with MCP Server and LLMs.txt.
-  ::
   ::card{icon="i-lucide-box" title="Module Author Guide" to="/docs/3.x/guide/modules"}
   Learn how to create Nuxt modules to integrate, enhance or extend any Nuxt application.
   ::

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/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/3.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

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/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/3.x/guide/going-further/nightly-release-channel).
 
 | Release               |                                                                                                                                                                                                                                                    | Initial release     | End Of Life                | Docs                                                              |
 |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|----------------------------|-------------------------------------------------------------------|
-| **5.x** (scheduled)   |                                                                                                                                                                                                                                                    | Q4 2025 (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/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-01-31                 | [nuxt.com](/docs/3.x/getting-started/introduction)                |
+| **5.x** (scheduled)   |                                                                                                                                                                                                                                                    | Q1 2026 (estimated) | TBA                        | &nbsp;                                                            |
+| **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-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/package.json

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