@nuxt/docs-nightly 5.0.0-29837649.bdf0b4f2 → 5.0.0-29837794.25b87beb

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

@@ -158,7 +158,7 @@ You can control this behavior with the [`experimental.payloadExtraction`](/docs/
 - `true` - The payload is extracted to a separate `_payload.json` file for both the initial render and client-side navigation. The HTML is smaller and the payload file can be cached by a CDN, at the cost of one extra request on first load.
 - `false` - Payload extraction is disabled. The payload is always inlined in the HTML and no `_payload.json` files are generated.
 
-The default is `true`, or `'client'` when `compatibilityVersion: 5` is set. It is forced to `false` when `ssr: false` is set.
+The default is `'client'`. It is forced to `false` when `ssr: false` is set.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({

package/3.guide/4.modules/9.server-compatibility.md

@@ -145,17 +145,20 @@ If we can't tell, code will be treated as `nitro2`.
 
 ## Nitro-specific Code
 
-`nuxt/server` covers request and response work: handlers, errors, query and body reading, headers, cookies, redirects, route rules and runtime config. But Nitro covers a lot more, so if you need any of these areas, you might need to stay on Nitro's own imports inside a `nitro2` or `nitro3` file.
+`nuxt/server` covers request and response work: handlers, errors, router params, query and body reading and validation, headers, CORS, cookies, sessions, redirects, route rules, runtime config and app config. But Nitro covers a lot more, so if you need any of these areas, you might need to stay on Nitro's own imports inside a `nitro2` or `nitro3` file.
 
 Use the specifiers of the version the file is for. A file that imports `nitro/*` is read as Nitro 3 code, so a `nitro2` file must import `h3` and `nitropack/*` instead:
 
 | Area | In a `nitro3` file | In a `nitro2` file |
 | --- | --- | --- |
 | Storage: `useStorage()` and its driver configuration | `nitro/storage` | `nitropack/runtime` |
-| Sessions: `useSession`, `getSession`, `updateSession`, `clearSession` | `nitro/h3` | `h3` |
 | Caching: `defineCachedHandler()`, `defineCachedFunction()` | `nitro/cache` | `nitropack/runtime` |
+| Server plugins | `definePlugin()` from `nitro` | `defineNitroPlugin()` from `nitropack/runtime` |
+| Runtime hooks, including `render:html` | `useNitroHooks()` from `nitro/app` | `useNitroApp().hooks` from `nitropack/runtime` |
+| App-relative fetch | `serverFetch()` from `nitro` | `useNitroApp().localFetch` from `nitropack/runtime` |
+| Lazy handlers: `lazyEventHandler()` | `nitro/h3` | `h3` |
 
-Nitro's runtime hooks (`useNitroApp().hooks`, including `render:html`) and tasks are obviously also not supported by `nuxt/server`.
+Tasks are also not supported by `nuxt/server`.
 
 ::read-more{to="/docs/guide/going-further/server-imports#reaching-past-the-surface"}
 See which h3 helpers work with the portable event, and which need Nitro-specific utilities.

package/3.guide/5.recipes/1.custom-routing.md

@@ -138,7 +138,7 @@ export default defineNuxtConfig({
 ```
 
 ::note
-With `future.compatibilityVersion: 5`, routing is case-sensitive by default to match Nitro. Set `router.options.sensitive` to `false` to opt out.
+Routing is case-sensitive by default to match Nitro. Set `router.options.sensitive` to `false` to opt out.
 ::
 
 ### Hash Mode (SPA)

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

@@ -193,23 +193,14 @@ export default defineNuxtConfig({
 ## parseErrorData
 
 ::warning
-This option is deprecated and will be removed. With `compatibilityVersion: 5` it is forced on and setting it is ignored.
+This option is deprecated and will be removed. It is forced on and setting it is ignored.
 ::
 
 Whether to parse `error.data` when rendering a server error page.
 
 It existed because the error was previously passed to the error page as individual query parameters, which stringified `error.data` and meant it had to be parsed back. Setting it to `false` opted out of that parsing and left you with the string.
 
-The error is now JSON-encoded as a whole, so `error.data` arrives with its original shape and is never stringified. On `compatibilityVersion: 4`, setting this to `false` stringifies it again so existing error pages that call `JSON.parse(error.data)` keep working:
-
-```ts twoslash [nuxt.config.ts]
-export default defineNuxtConfig({
-  future: { compatibilityVersion: 4 },
-  experimental: {
-    parseErrorData: false,
-  },
-})
-```
+The error is now JSON-encoded as a whole, so `error.data` arrives with its original shape and is never stringified.
 
 ## payloadExtraction
 
@@ -219,7 +210,7 @@ Controls how payload data is delivered for prerendered and cached (ISR/SWR) page
 - `true` - Payload is extracted to a separate `_payload.json` file for both the initial server render and client-side navigation.
 - `false` - Payload extraction is disabled entirely. Payload is always inlined in HTML and no `_payload.json` files are generated.
 
-The default is `true`, or `'client'` when `compatibilityVersion: 5` is set. It is forced to `false` when `ssr: false` is set.
+The default is `'client'`. It is forced to `false` when `ssr: false` is set.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -243,12 +234,12 @@ When enabled, `.client.vue` components and `createClientOnly()` wrappers render
 Enabling this means attributes (`class`, `style`, etc.) passed to `.client.vue` components will not appear in the SSR HTML. If you need styled placeholders to prevent layout shift, use `<ClientOnly>` with a `#fallback` slot instead.
 ::
 
-This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can also enable it explicitly:
+This flag is enabled by default, but you can disable it:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    clientNodePlaceholder: true,
+    clientNodePlaceholder: false,
   },
 })
 ```
@@ -478,8 +469,7 @@ You can also set this to `chokidar` to watch all files in your source directory.
 
 Set to `'builder'` to reuse the active builder's own file watcher (for example,
 Vite's `server.watcher`) instead of starting a second one. This reduces the
-number of file watchers active in dev mode and becomes the default when
-`future.compatibilityVersion` is `5`. If the active builder does not implement
+number of file watchers active in dev mode and is the default. If the active builder does not implement
 its own watcher (currently webpack and rspack), Nuxt logs a warning and falls
 back to its default selection.
 
@@ -656,7 +646,7 @@ This allows modules to access additional metadata from the page metadata in the
 
 ## extractSerializablePageMeta
 
-Enabled by default when `future.compatibilityVersion` is `5` or higher.
+Enabled by default.
 
 By default, Nuxt only reads a fixed list of `definePageMeta()` keys at build time (plus anything in `extraPageMetaExtractionKeys`); everything else is resolved at runtime from a separate module generated per page. With this option, Nuxt writes every JSON-serializable property straight into the generated route record instead.
 
@@ -705,7 +695,7 @@ Transform top-level `await navigateTo()` calls in `<script setup>` into an early
 
 Without this flag, code after `await navigateTo()` continues to run, which can result in later code (including subsequent `navigateTo` calls) overriding the redirect or attempting to render a page with missing data. With this flag enabled, a successful navigation stops execution of the rest of your setup code and the component renders a placeholder comment while the navigation proceeds.
 
-This flag is enabled by default with `compatibilityVersion: 5`, but you can disable it:
+This flag is enabled by default, but you can disable it:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -773,7 +763,7 @@ By default, Vue assigns component names based on the filename. For example, `pag
 
 With `normalizePageNames` enabled, page components are named after their route (e.g. `foo` and `bar`), so you can use `<KeepAlive>` with `include`/`exclude` without manually adding `defineOptions({ name: '...' })` to each page.
 
-This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can disable this feature:
+This flag is enabled by default, but you can disable this feature:
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -992,7 +982,7 @@ export default defineNuxtConfig({
 })
 ```
 
-The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
+The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true`.
 
 ## purgeCachedData
 

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

@@ -95,22 +95,8 @@ See the mostly-static site recipe for combining `noScripts` with prerendering, i
 
 There is also a `future` namespace for early opting-in to new features that will become default in a future (possibly major) version of the framework.
 
-### compatibilityVersion
-
-This enables early access to Nuxt features or flags.
-
-On Nuxt 5 it resolves to `5`, and the defaults described in the upgrade guide apply. Individual changes are configured through the options named there rather than through this one.
-
-```ts
-export default defineNuxtConfig({
-  future: {
-    compatibilityVersion: 5,
-  },
-})
-```
-
-::read-more{to="/docs/getting-started/upgrade#migrating-to-nuxt-5"}
-Learn more about migrating to Nuxt 5.
+::note
+`future.compatibilityVersion` always resolves to `5` in Nuxt 5. To opt into Nuxt 5 behaviour on Nuxt 4, see the [Nuxt 4 documentation](https://nuxt.com/docs/4.x/getting-started/upgrade#testing-nuxt-5).
 ::
 
 ### multiApp

package/3.guide/6.going-further/5.server-imports.md

@@ -36,21 +36,24 @@ This code can run under `@nuxt/nitro-server` and under `@nuxt/vite-server`, and
 | `createError`, `isNuxtError` | Construct and recognise an HTTP error. |
 | `getRequestURL` | The URL of the request. |
 | `getRequestHeader`, `getRequestHeaders` | Read request headers. |
-| `getQuery` | Read the query string. |
-| `readBody` | Read and parse the request body. |
+| `getRouterParam`, `getRouterParams` | Read the dynamic segments matched for the request. |
+| `getRequestIP` | The client IP address, with [forwarded headers trusted on request](#client-ip). |
+| `getQuery`, `getValidatedQuery` | Read the query string, optionally [validated](#validation). |
+| `readBody`, `readValidatedBody` | Read and parse the request body, optionally [validated](#validation). |
 | `getCookie`, `setCookie`, `deleteCookie` | Read and write cookies. |
 | `setResponseStatus` | Set the response status and reason phrase. |
-| `setResponseHeader`, `setResponseHeaders` | Set response headers. |
+| `handleCors` | Apply [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) headers and answer preflight requests. |
 | `sendRedirect` | Redirect the request. |
 | `useSession`, `getSession`, `updateSession`, `clearSession` | Read and write a [sealed session cookie](#sessions). |
 | `deriveSecret` | A purpose-specific secret [derived from `appSecret`](#deriving-secrets). |
 | `getRouteRules` | The [route rules](/docs/guide/concepts/rendering#route-rules) matched for the request. |
 | `useRuntimeConfig` | The server's [runtime configuration](/docs/guide/going-further/runtime-config). |
+| `useAppConfig` | The [app config](/docs/directory-structure/app/app-config), as a copy per request when passed the event. |
 | `toNuxtRequestEvent` | The event in the shape the server runtime provides. |
 
-Types are exported alongside the utilities: `RequestEvent`, `RequestEventContext`, `NuxtRequestEvent`, `EventHandler`, `AppRouteRules`, `ServerRoutes`, `NuxtError`, `NuxtErrorDetails`, `NuxtErrorJSON`, `NuxtErrorLike`, `Session`, `SessionConfig`, `SessionData`, `SessionEvent`, `SessionManager`, `SessionPassword` and `SessionUpdate`.
+Types are exported alongside the utilities: `RequestEvent`, `RequestEventContext`, `NuxtRequestEvent`, `EventHandler`, `AppRouteRules`, `ServerRoutes`, `CorsOptions`, `ValidateResult`, `NuxtError`, `NuxtErrorDetails`, `NuxtErrorJSON`, `NuxtErrorLike`, `Session`, `SessionConfig`, `SessionData`, `SessionEvent`, `SessionManager`, `SessionPassword` and `SessionUpdate`.
 
-These names are [auto-imported](/docs/directory-structure/server) in server code, so the import statement above is optional. Writing it keeps the file working in a project with server auto-imports off, and is what a module should do.
+These names, except `useAppConfig`, are [auto-imported](/docs/directory-structure/server) in server code, so the import statement above is optional. Writing it keeps the file working in a project with server auto-imports off, and is what a module should do.
 
 ::tip
 `defineEventHandler` preserves your handler's return type, which is what types [`$fetch` and `useFetch`](/docs/getting-started/data-fetching) calls to the route. Annotate the value you return rather than the handler.
@@ -69,6 +72,8 @@ interface RequestEvent {
 }
 ```
 
+To set, read, append or remove a response header, use `event.res.headers` directly: it is a standard `Headers` object.
+
 Nitro adds more on top, such as `event.node`, `event.runtime` and `event.waitUntil()`, but these four core properties work in all runtimes, and need no helpers:
 
 ```ts [server/api/echo.post.ts]
@@ -80,6 +85,28 @@ export default defineEventHandler(async (event) => {
 
 `NuxtRequestEvent` is the same request in the shape the configured builder provides, which is h3's `H3Event` under `@nuxt/nitro-server`. You can get a type-safe version of the event for the server builder you're using by calling `toNuxtRequestEvent(event)`.
 
+## Validation
+
+`readValidatedBody` and `getValidatedQuery` take any [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType and others), or a function that returns the validated value, `true` to accept the input or `false` to reject it.
+
+```ts [server/api/users.post.ts]
+import { defineEventHandler, readValidatedBody } from 'nuxt/server'
+import { z } from 'zod'
+
+export default defineEventHandler(async (event) => {
+  const user = await readValidatedBody(event, z.object({ name: z.string() }))
+  return { created: user.name }
+})
+```
+
+Invalid input is rejected with a `400` whose `data.issues` lists what failed. Pass `onError` to reject it with a different error.
+
+## Client IP
+
+`getRequestIP(event)` returns the address the server runtime reports for the connection, or `undefined` if it reports none. No forwarded header is trusted by default, because a client can send any value in one.
+
+Behind a proxy you control, pass `{ xForwardedFor: true }` to read the first entry of `X-Forwarded-For` instead. Only do this when the proxy overwrites the header: a proxy that appends to it leaves a client-sent value first.
+
 ## Sessions
 
 `useSession` reads the session for the request, sealing a new one into a cookie when there is none to read. The data is sealed with [iron](https://github.com/brc-dd/iron-webcrypto), so it lives in the cookie rather than in server storage, and the cookie defaults to `httpOnly`, `secure`, `sameSite: 'lax'` and `path: '/'`.
@@ -126,52 +153,48 @@ Most of those helpers take the event as it is:
 
 ```ts [server/api/upload.post.ts]
 import { defineEventHandler } from 'nuxt/server'
-import { readValidatedBody } from 'nitro/h3'
+import { readMultipartFormData } from 'nitro/h3'
 
 export default defineEventHandler(async (event) => {
-  const body = await readValidatedBody(event, schema)
-  return { received: body }
+  const parts = await readMultipartFormData(event)
+  return { received: parts?.length ?? 0 }
 })
 ```
 
-That works for any h3 helper that only reads the request: `readValidatedBody`, `getValidatedQuery`, `getRouterParam`, `getRouterParams`, `getRequestIP` and `assertMethod`.
+That works for any h3 helper that only reads the request, such as `readRawBody`, `readFormData`, `readMultipartFormData` and `assertMethod`.
 
 A helper that needs the runtime's own event gets it from `toNuxtRequestEvent`:
 
-```ts [server/api/cors.ts]
+```ts [server/api/proxy.ts]
 import { defineEventHandler, toNuxtRequestEvent } from 'nuxt/server'
-import { handleCors } from 'nitro/h3'
+import { proxyRequest } from 'nitro/h3'
 
-export default defineEventHandler((event) => {
-  handleCors(toNuxtRequestEvent(event), { origin: '*' })
-  return { ok: true }
-})
+export default defineEventHandler(event => proxyRequest(toNuxtRequestEvent(event), 'https://example.com'))
 ```
 
-Helpers that need you to call `toNuxtRequestEvent` are the CORS helpers (such as `handleCors`), `proxy`, `proxyRequest`, `fetchWithEvent`, `writeEarlyHints`, and reading `event.node`, `event.waitUntil()` or `event.runtime`. The helper works on every builder, and a cast to `NuxtRequestEvent` is safe even if the runtime's event is web-shaped, as it is under `@nuxt/nitro-server`.
+Helpers that need you to call `toNuxtRequestEvent` are `proxy`, `proxyRequest`, `fetchWithEvent`, `writeEarlyHints`, and reading `event.node`, `event.waitUntil()` or `event.runtime`. The helper works on every builder, and a cast to `NuxtRequestEvent` is safe even if the runtime's event is web-shaped, as it is under `@nuxt/nitro-server`.
 
 Nitro's own APIs mostly take no event at all: `getRouteRules(method, pathname)`, `serverFetch()`, `defineCachedHandler()`, `useStorage()`, `useDatabase()` and tasks.
 
 ::tip
 If you find you are writing Nitro-specific code, you may simply prefer to import `defineEventHandler` from `nitro/h3` instead:
 
-```ts [server/api/cors.ts]
-import { defineEventHandler, handleCors } from 'nitro/h3'
+```ts [server/api/proxy.ts]
+import { defineEventHandler, proxyRequest } from 'nitro/h3'
 
-export default defineEventHandler((event) => {
-  handleCors(event, { origin: '*' })
-  return { ok: true }
-})
+export default defineEventHandler(event => proxyRequest(event, 'https://example.com'))
 ```
 ::
 
 ## What Isn't Portable
 
-Three key areas you may need will mean you need to reach outside `nuxt/server`, because Nuxt can't provide them for every builder:
+These areas mean reaching outside `nuxt/server`, because Nuxt can't provide them for every builder:
 
 - **Storage.** `useStorage()` comes from `nitro/storage`, and so does the driver configuration behind it.
-- **Sessions.** The sealed-session helpers come from `nitro/h3`. They accept the portable event, but importing them pins the file to Nitro.
-- **Caching.** `defineCachedHandler()` and `defineCachedFunction()` come from `nitro/cache`.
+- **Caching.** `defineCachedHandler()` and `defineCachedFunction()` come from `nitro/cache`. For caching that runs anywhere, depend on a cache library directly.
+- **Server plugins and hooks.** `definePlugin()` comes from `nitro`, and the runtime hooks (including `render:html`) from `useNitroHooks()` in `nitro/app`.
+- **App-relative fetch.** `serverFetch()` comes from `nitro`. It calls a route of the app without an origin, which needs the runtime's router.
+- **Lazy handlers.** `lazyEventHandler()` comes from `nitro/h3`.
 
 ## Server Code Only
 

package/4.api/2.composables/use-server-seo-meta.md

@@ -9,7 +9,7 @@ links:
 ---
 
 ::warning
-`useServerSeoMeta` is deprecated. Wrap [`useSeoMeta`](/docs/api/composables/use-seo-meta) in an `if (import.meta.server)` block instead. The auto-import is removed under `future.compatibilityVersion: 5`.
+`useServerSeoMeta` is deprecated. Wrap [`useSeoMeta`](/docs/api/composables/use-seo-meta) in an `if (import.meta.server)` block instead. It is no longer auto-imported.
 ::
 
 `useServerSeoMeta` lets you define your site's SEO meta tags as a flat object with full TypeScript support, exactly like [`useSeoMeta`](/docs/api/composables/use-seo-meta), but it only runs server-side and is tree-shaken from the client bundle.

package/4.api/3.utils/clear-nuxt-state.md

@@ -23,4 +23,4 @@ export function clearNuxtState (keys?: string | string[] | ((key: string) => boo
 
 - `keys`: One or an array of keys that are used in [`useState`](/docs/api/composables/use-state) to delete their cached state. If no keys are provided, **all state** will be invalidated.
 - `opts`: An options object to configure the clear behavior.
-  - `reset` :badge[v4.4]{color="info" size="xs" class="align-middle"}: When set to `true`, resets the state to the initial value provided by the `init` function of [`useState`](/docs/api/composables/use-state) instead of setting it to `undefined`. When not specified, defaults to the value of `experimental.defaults.useState.resetOnClear` in your Nuxt config (which is `true` with `compatibilityVersion: 5`).
+  - `reset` :badge[v4.4]{color="info" size="xs" class="align-middle"}: When set to `true`, resets the state to the initial value provided by the `init` function of [`useState`](/docs/api/composables/use-state) instead of setting it to `undefined`. When not specified, defaults to the value of `experimental.defaults.useState.resetOnClear` in your Nuxt config (which defaults to `true`).

package/4.api/6.advanced/2.import-meta.md

@@ -19,7 +19,7 @@ Read more about `import.meta`.
 These values are statically injected and can be used for tree-shaking your runtime code.
 
 ::note
-`process.browser`, `process.client`, `process.dev`, `process.server`, and `process.test` were soft-deprecated in Nuxt 3.12. In Nuxt 5 or with `future.compatibilityVersion: 5`, Nuxt no longer augments `NodeJS.Process` with those properties. Prefer the matching `import.meta.*` flags; build-time `process.*` defines still exist for compatibility.
+`process.browser`, `process.client`, `process.dev`, `process.server`, and `process.test` were soft-deprecated in Nuxt 3.12. In Nuxt 5, Nuxt no longer augments `NodeJS.Process` with those properties. Prefer the matching `import.meta.*` flags; build-time `process.*` defines still exist for compatibility.
 ::
 
 Property | Type | Description

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29837649.bdf0b4f2",
+  "version": "5.0.0-29837794.25b87beb",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",