@nuxt/docs 3.21.0 → 3.21.2

package/1.getting-started/02.installation.md

@@ -20,13 +20,14 @@ Or follow the steps below to set up a new Nuxt project on your computer.
 ### Prerequisites
 
 - **Node.js** - [`20.x`](https://nodejs.org/en) or newer (but we recommend the [active LTS release](https://github.com/nodejs/release#release-schedule))
-- **Text editor** - There is no IDE requirement, but we recommend [Visual Studio Code](https://code.visualstudio.com/) with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously known as Volar) or [WebStorm](https://www.jetbrains.com/webstorm/), which, along with [other JetBrains IDEs](https://www.jetbrains.com/ides/), offers great Nuxt support right out-of-the-box.
+- **Text editor** - There is no IDE requirement, but we recommend [Visual Studio Code](https://code.visualstudio.com/) with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously known as Volar) or [WebStorm](https://www.jetbrains.com/webstorm/), which, along with [other JetBrains IDEs](https://www.jetbrains.com/ides/), offers great Nuxt support right out-of-the-box. If you use another editor, such as Neovim, you can configure [Vue Language Server](https://github.com/vuejs/language-tools) support by following the [Vue Language Tools setup guides](https://github.com/vuejs/language-tools/wiki).
 - **Terminal** - In order to run Nuxt commands
 
 ::note
   ::details
   :summary[Additional notes for an optimal setup:]
   - **Node.js**: Make sure to use an even numbered version (20, 22, etc.)
+  - **Neovim**: When configuring the Vue TypeScript plugin, make sure `location` points to the `@vue/language-server` package directory, not its binary. See the [Neovim setup guide](https://github.com/vuejs/language-tools/wiki/Neovim) for a working configuration.
   - **WSL**: If you are using Windows and experience slow HMR, you may want to try using [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install) which may solve some performance issues.
   - **Windows slow DNS resolution**: Instead of using `localhost:3000` for local dev server on Windows, use `127.0.0.1` for much faster loading experience on browsers.
   ::

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

package/1.getting-started/16.deployment.md

@@ -120,9 +120,8 @@ In most cases, Nuxt can work with third-party content that is not generated or c
 
 Accordingly, you should make sure that the following options are unchecked / disabled in Cloudflare. Otherwise, unnecessary re-rendering or hydration errors could impact your production application.
 
-1. Speed > Optimization > Content Optimization > Disable "Rocket Loader™"
-2. Speed > Optimization > Image Optimization > Disable "Mirage"
-3. Scrape Shield > Disable "Email Address Obfuscation"
+1. Speed > Settings > Content Optimization > Disable "Rocket Loader™"
+2. Security > Settings > Disable "Email Address Obfuscation"
 
 With these settings, you can be sure that Cloudflare won't inject scripts into your Nuxt application that may cause unwanted side effects.
 

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

@@ -108,6 +108,7 @@ If you prefer a simpler setup and want all tests to run in the Nuxt environment,
 
 ```ts twoslash
 import { defineVitestConfig } from '@nuxt/test-utils/config'
+import { fileURLToPath } from 'node:url'
 
 export default defineVitestConfig({
   test: {
@@ -268,6 +269,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.
@@ -320,14 +325,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' }
   }
@@ -336,6 +345,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).
 ::
@@ -346,24 +376,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.
@@ -445,6 +494,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/3.x/getting-started/configuration#environment-overrides) (`$test`) so all your requests will go to Nitro server.
 
 #### Conflict with End-To-End Testing
@@ -458,7 +513,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

@@ -192,6 +192,7 @@ Nuxt now defaults to a new directory structure, with backwards compatibility (so
 - `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
 - if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
 - a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`
+- a new [`shared/`](/docs/3.x/directory-structure/shared) directory is available for code shared between the Vue app and the Nitro server, with auto-imports for `shared/utils/` and `shared/types/`
 
 <details>
 
@@ -218,6 +219,8 @@ modules/
 node_modules/
 public/
 shared/
+  types/
+  utils/
 server/
   api/
   middleware/
@@ -246,14 +249,14 @@ With this new structure, the `~` alias now points to the `app/` directory by def
 
 1. Create a new directory called `app/`.
 1. Move your `assets/`, `components/`, `composables/`, `layouts/`, `middleware/`, `pages/`, `plugins/` and `utils/` folders under it, as well as `app.vue`, `error.vue`, `app.config.ts`. If you have an `app/router-options.ts` or `app/spa-loading-template.html`, these paths remain the same.
-1. Make sure your `nuxt.config.ts`, `content/`, `layers/`, `modules/`, `public/` and `server/` folders remain outside the `app/` folder, in the root of your project.
+1. Make sure your `nuxt.config.ts`, `content/`, `layers/`, `modules/`, `public/`, `shared/` and `server/` folders remain outside the `app/` folder, in the root of your project.
 1. Remember to update any third-party configuration files to work with the new directory structure, such as your `tailwindcss` or `eslint` configuration (if required - `@nuxtjs/tailwindcss` should automatically configure `tailwindcss` correctly).
 
 ::tip
 You can automate this migration by running `npx codemod@latest nuxt/4/file-structure`
 ::
 
-However, migration is _not required_. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you _already_ have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.
+However, migration is _not required_. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you _already_ have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/`, `shared/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.
 
 You can also force a v3 folder structure with the following configuration:
 

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

@@ -122,7 +122,7 @@ File | Layout Name
 
 You can also use the [`setPageLayout`](/docs/3.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/2.directory-structure/1.modules.md

@@ -52,6 +52,10 @@ export default defineEventHandler(() => {
 
 When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available.
 
+::note
+Note that all components, pages, composables and other files that would be normally placed in your `app/` directory need to be in `modules/your-module/runtime/app/`. This ensures they can be type-checked properly.
+::
+
 Modules are executed in the following sequence:
 - First, the modules defined in [`nuxt.config.ts`](/docs/3.x/api/nuxt-config#modules-1) are loaded.
 - Then, modules found in the `modules/` directory are executed, and they load in alphabetical order.

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.
 
@@ -228,7 +228,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) => {
@@ -238,7 +238,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/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/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/2.best-practices/performance.md

@@ -142,9 +142,8 @@ Images in your website can usually be separated by importance; the ones that are
   <NuxtImg
     src="/hero-banner.jpg"
     format="webp"
-    preload
+    :preload="{ fetchPriority: 'high' }"
     loading="eager"
-    fetch-priority="high"
     width="200"
     height="100"
   />
@@ -154,7 +153,7 @@ Images in your website can usually be separated by importance; the ones that are
     src="/facebook-logo.jpg"
     format="webp"
     loading="lazy"
-    fetch-priority="low"
+    fetchpriority="low"
     width="200"
     height="100"
   />

package/3.guide/3.ai/1.mcp.md

@@ -79,7 +79,7 @@ The Nuxt connector will appear in the composer's "Developer mode" tool later dur
 ### Claude Code
 
 ::note{icon="i-lucide-info"}
-**Ensure Claude Code is installed** - Visit [Anthropic's documentation](https://docs.claude.com/en/docs/claude-code/quickstart) for installation instructions.
+**Ensure Claude Code is installed** - Visit [Anthropic's documentation](https://code.claude.com/docs/en/quickstart) for installation instructions.
 ::
 
 Add the server using the CLI command:

package/3.guide/3.ai/2.llms-txt.md

@@ -42,7 +42,7 @@ Nuxt provides specialized LLMs.txt files that you can reference in Cursor for be
 1. **Direct reference**: Mention the LLMs.txt URLs when asking questions
 2. Add these specific URLs to your project context using `@docs`
 
-[Read more about Cursor Web and Docs Search](https://cursor.com/docs/context/symbols)
+[Read more about Cursor Web and Docs Search](https://cursor.com/docs/context/mentions)
 
 ### Windsurf
 

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

@@ -139,6 +139,10 @@ 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.
 ::
 
+::note
+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 Composables
 
 If your module should provide composables, you can use the `addImports` utility to add them as auto-imports for Nuxt to resolve.
@@ -200,6 +204,100 @@ 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
+}
+
+// ...
+```
+::
+
+::note
+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 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),
 })
 
@@ -210,7 +210,7 @@ We've successfully set up a very basic user authentication and session managemen
 
 As next steps, you can:
 - Add authentication using the [20+ supported OAuth providers](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#supported-oauth-providers)
-- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/features/database)
+- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/database)
 - Let user signup with email & password using [password hashing](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#password-hashing)
 - Add support for [WebAuthn / Passkeys](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#webauthn-passkey)
 

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

@@ -370,7 +370,11 @@ Out of the box, this will enable typed usage of [`navigateTo`](/docs/3.x/api/uti
 You can even get typed params within a page by using `const route = useRoute('route-name')`.
 
 ::important
-If you use `pnpm` without `shamefully-hoist=true`, you will need to have `unplugin-vue-router` installed as a devDependency in order for this feature to work.
+If you use `pnpm` without `shamefully-hoist=true`, you will need to add `unplugin-vue-router` as a hoist pattern in your `pnpm-workspace.yaml` in order for this feature to work.
+```yaml
+publicHoistPattern:
+  - "unplugin-vue-router"
+```
 ::
 
 :video-accordion{title="Watch a video from Daniel Roe explaining type-safe routing in Nuxt" videoId="SXk-L19gTZk"}

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/3.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/1.components/8.nuxt-island.md

@@ -74,4 +74,4 @@ Some slots are reserved to `NuxtIsland` for special cases.
   - **parameters**:
     - **error**:
       - **type**: `unknown`
-  - **description**: emitted when when `NuxtIsland` fails to fetch the new island.
+  - **description**: emitted when `NuxtIsland` fails to fetch the new island.

package/4.api/2.composables/use-async-data.md

@@ -148,7 +148,7 @@ The `handler` function should be **side-effect free** to ensure predictable beha
   - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`)
   - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option
   - `transform`: a function that can be used to alter `handler` function result after resolving
-  - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is:
+  - `getCachedData`: Provide a function which returns cached data. An `undefined` return value will trigger a fetch. By default, this is:
     ```ts
     const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
       ? nuxtApp.payload.data[key]

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

@@ -161,6 +161,7 @@ type AsyncDataRequestContext = {
 
 type AsyncData<DataT, ErrorT> = {
   data: Ref<DataT | null>
+  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/3.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/3.x/api/composables/use-fetch#return-values"}

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/4.commands/build.md

@@ -32,7 +32,7 @@ The `build` command creates a `.output` directory with all your application, ser
 | `--cwd=<directory>`                  |         | Specify the working directory, this takes precedence over ROOTDIR (default: `.`)                                                                     |
 | `--logLevel=<silent\|info\|verbose>` |         | Specify build-time log level                                                                                                                         |
 | `--prerender`                        |         | Build Nuxt and prerender static routes                                                                                                               |
-| `--preset`                           |         | Nitro server preset                                                                                                                                  |
+| `--preset=<preset>`                  |         | Specify Nitro server preset. Available presets depend on Nitro (e.g. `node-server`, `vercel`, `netlify`, `static`)                                  |
 | `--dotenv`                           |         | Path to `.env` file to load, relative to the root directory                                                                                          |
 | `--envName`                          |         | The environment to use when resolving configuration overrides (default is `production` when building, and `development` when running the dev server) |
 | `-e, --extends=<layer-name>`         |         | Extend from a Nuxt layer                                                                                                                             |

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/3.x/directory-structure/shared) directory, the function must be imported from the same source file for both [`addImports`](/docs/3.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/3.x/api/kit/nitro#addserverimports) function.
+::
 
 ### Usage
 

package/5.community/2.getting-help.md

@@ -41,7 +41,7 @@ We recommend taking a look at [how to report bugs](/docs/3.x/community/reporting
 
 ## "I need professional help"
 
-If the community couldn't provide the help you need in the time-frame you have, NuxtLabs offers professional support with the [Nuxt Experts](https://nuxt.com/enterprise/support).
+If the community couldn't provide the help you need in the time-frame you have, NuxtLabs offers professional support with the [Nuxt Experts](https://nuxt.com/enterprise/agencies).
 
 The objective of the Nuxt Expert is to provide support to the Vue ecosystem, while also creating freelance opportunities for those contributing to open-source solutions, thus helping to maintain the sustainability of the ecosystem.
 

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/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/3.x/directory-structure/server"}

package/package.json

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