@nuxt/docs-nightly 4.3.1-29507030.8e4f35f8 → 4.3.1-29507514.0ed26bbf

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/4.api/6.nuxt-config.md

@@ -1014,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**
@@ -1023,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"
   }
 ]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.3.1-29507030.8e4f35f8",
+  "version": "4.3.1-29507514.0ed26bbf",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",