@nuxt/docs 4.3.0 → 4.4.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/09.transitions.md

@@ -459,6 +459,106 @@ definePageMeta({
 Overriding view transitions on a per-page basis will only have an effect if you have enabled the `experimental.viewTransition` option.
 ::
 
+### View Transition Types
+
+[View transition types](https://developer.chrome.com/blog/view-transitions-update-io24#view-transition-types) allow you to apply different CSS animations depending on the type of navigation. This is useful for creating asymmetric transitions (e.g., a different animation when navigating forward vs. backward).
+
+Types are set on the [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition) and can be targeted in CSS using the [`:active-view-transition-type()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:active-view-transition-type) pseudo-class selector.
+
+You can set default types globally in your `nuxt.config.ts`:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  app: {
+    viewTransition: {
+      enabled: true,
+      types: ['slide'],
+    },
+  },
+})
+```
+
+Or configure types per-page using `definePageMeta`. Per-page types support both static arrays and functions for dynamic behavior:
+
+```vue twoslash [pages/detail.vue]
+<script setup lang="ts">
+definePageMeta({
+  viewTransition: {
+    enabled: true,
+    // Types applied to any transition involving this page
+    types: ['slide'],
+    // Types applied only when navigating TO this page
+    toTypes: ['slide-in'],
+    // Types applied only when navigating FROM this page
+    fromTypes: ['slide-out'],
+  },
+})
+</script>
+```
+
+You can also use functions for `types`, `toTypes`, and `fromTypes` in `definePageMeta` to determine types dynamically based on the route:
+
+```vue twoslash [pages/[id].vue]
+<script setup lang="ts">
+definePageMeta({
+  viewTransition: {
+    enabled: true,
+    toTypes: (to, from) => {
+      // Slide left when going to a higher ID, right otherwise
+      return Number(to.params.id) > Number(from.params.id)
+        ? ['slide-left']
+        : ['slide-right']
+    },
+  },
+})
+</script>
+```
+
+Then target these types in your CSS:
+
+```css
+/* Default crossfade */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 0.3s;
+}
+
+/* Slide left animation */
+html:active-view-transition-type(slide-left) {
+  &::view-transition-old(root) {
+    animation: slide-out-left 0.3s ease-in-out;
+  }
+  &::view-transition-new(root) {
+    animation: slide-in-right 0.3s ease-in-out;
+  }
+}
+
+/* Slide right animation */
+html:active-view-transition-type(slide-right) {
+  &::view-transition-old(root) {
+    animation: slide-out-right 0.3s ease-in-out;
+  }
+  &::view-transition-new(root) {
+    animation: slide-in-left 0.3s ease-in-out;
+  }
+}
+```
+
+::note
+Function values for `types`, `toTypes`, and `fromTypes` only work in `definePageMeta`, not in `nuxt.config.ts` (where only static `string[]` is supported).
+::
+
+The `page:view-transition:start` hook provides access to the [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition) object, which includes a [`types`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition/types) property (`ViewTransitionTypeSet`) that can be read or modified at runtime:
+
+```ts [plugins/view-transition.client.ts]
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('page:view-transition:start', (transition) => {
+    // Read or modify types at runtime
+    console.log([...transition.types])
+  })
+})
+```
+
 If you are also using Vue transitions like `pageTransition` and `layoutTransition` (see above) to achieve the same result as the new View Transitions API, then you may wish to _disable_ Vue transitions if the user's browser supports the newer, native web API. You can do this by creating `~/middleware/disable-vue-transitions.global.ts` with the following contents:
 
 ```ts

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/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: {
@@ -299,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.
@@ -351,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' }
   }
@@ -367,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).
 ::
@@ -377,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.
@@ -476,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
@@ -489,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

@@ -59,6 +59,9 @@ export default defineNuxtConfig({
 When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:
 
 - **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
@@ -178,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.
@@ -272,6 +321,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/4.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>
 
@@ -298,6 +348,8 @@ modules/
 node_modules/
 public/
 shared/
+  types/
+  utils/
 server/
   api/
   middleware/
@@ -326,14 +378,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/`, `app/layouts/`, `app/middleware/`, `app/pages/`, `app/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:
 
@@ -846,6 +898,55 @@ If you provide a custom `default` value for `useAsyncData`, this will now be use
 
 Often users set an appropriately empty value, such as an empty array, to avoid the need to check for `null`/`undefined` when iterating over it. This should be respected when resetting/clearing the data.
 
+### Respect defaults when clearing `useState`
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+With `compatibilityVersion: 5`, `clearNuxtState` will reset state to its initial value (provided by the `init` function of `useState`) instead of setting it to `undefined`. This aligns `clearNuxtState` behavior with `clearNuxtData`, which already resets to defaults.
+
+#### Reasons for Change
+
+When `clearNuxtState` sets state to `undefined`, composables that depend on that state can crash because they expect the state to always have a valid shape (e.g., accessing properties on `undefined`). Resetting to the `init` value ensures state always has a usable default.
+
+#### Migration Steps
+
+If you rely on `clearNuxtState` setting state to `undefined`, you can explicitly pass `{ reset: false }`:
+
+```diff
+- clearNuxtState('myKey')
++ clearNuxtState('myKey', { reset: false })
+```
+
+Alternatively, you can revert to the previous behavior with:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    defaults: {
+      useState: {
+        resetOnClear: false,
+      },
+    },
+  },
+})
+```
+
+You can also opt in to this behavior today without setting `compatibilityVersion: 5`:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    defaults: {
+      useState: {
+        resetOnClear: true,
+      },
+    },
+  },
+})
+```
+
 ### Alignment of `pending` value in `useAsyncData` and `useFetch`
 
 🚦 **Impact Level**: Medium
@@ -1321,6 +1422,41 @@ export default defineNuxtConfig({
 Read more about Nitro's prerender configuration options.
 ::
 
+### Normalized Page Component Names
+
+🚦 **Impact Level**: Minimal
+
+#### What Changed
+
+When `future.compatibilityVersion` is set to `5` (or `experimental.normalizePageNames` is enabled), page component names match their route names instead of using the filename. For example, `pages/foo/index.vue` will have the component name `foo` instead of `index`.
+
+#### Reasons for Change
+
+Previously, Vue assigned component names based on the filename. This meant multiple pages like `pages/foo/index.vue` and `pages/bar/index.vue` would both have the component name `index`. This made `<KeepAlive>` with `include`/`exclude` filters unreliable and required manually adding `defineOptions({ name: '...' })` to each page.
+
+#### Migration Steps
+
+If you rely on the current component names (e.g. in `<KeepAlive>` `include`/`exclude` lists), update them to use route names instead of filenames.
+
+```diff
+<template>
+  <NuxtPage :keepalive="{
+-   include: ['index']
++   include: ['foo']
+  }" />
+</template>
+```
+
+To disable this behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    normalizePageNames: false,
+  },
+})
+```
+
 ## Nuxt 2 vs. Nuxt 3+
 
 In the table below, there is a quick comparison between 3 versions of Nuxt:

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 {
@@ -168,6 +168,65 @@ This is useful when you want to manage layouts centrally in your configuration r
 
 :link-example{to="/docs/4.x/examples/features/layouts"}
 
+## Passing Props to Layouts
+
+You can pass props to layouts in several ways.
+
+### Via `definePageMeta`
+
+Use the object syntax for the `layout` property to pass props directly from your page:
+
+::code-group
+
+```vue [app/pages/dashboard.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: {
+    name: 'panel',
+    props: {
+      sidebar: true,
+      title: 'Dashboard',
+    },
+  },
+})
+</script>
+```
+
+```vue [app/layouts/panel.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  sidebar?: boolean
+  title?: string
+}>()
+</script>
+
+<template>
+  <div>
+    <aside v-if="sidebar">
+      Sidebar
+    </aside>
+    <main>
+      <h1>{{ title }}</h1>
+      <slot />
+    </main>
+  </div>
+</template>
+```
+
+::
+
+::tip
+Props are fully typed based on your layout's `defineProps`. You'll get autocomplete and type-checking in your editor.
+::
+
+### Via `setPageLayout`
+
+You can also pass props when changing the layout dynamically with [`setPageLayout`](/docs/4.x/api/utils/set-page-layout):
+
+```ts
+setPageLayout('panel', { sidebar: true, title: 'Dashboard' })
+```
+
 ## Overriding a Layout on a Per-page Basis
 
 If you are using pages, you can take full control by setting `layout: false` and then using the `<NuxtLayout>` component within the page.

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