@nuxt/docs-nightly 5.0.0-29837688.ef8d0fbb → 5.0.0-29837794.25b87beb

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/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/package.json

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