@nuxt/docs-nightly 4.6.0-29837544.9d4d1eda → 4.6.0-29838870.2da76d24

package/1.getting-started/18.upgrade.md

@@ -60,6 +60,9 @@ Defaults throughout your Nuxt configuration then change to opt in to Nuxt 5 beha
 - **`clearNuxtState` resets to defaults**: `clearNuxtState` resets state to the initial value of [`useState`](/docs/api/composables/use-state) instead of setting it to `undefined`
 - **Non-async `callHook`**: `callHook` may return `void` instead of always returning a `Promise`
 - **Early return from `navigateTo`**: [`experimental.navigateToEarlyReturn`](/docs/guide/going-further/experimental-features#navigatetoearlyreturn) stops a middleware continuing after it redirects
+- **Server-only head composables**: `useServerHead`, `useServerHeadSafe` and `useServerSeoMeta` are no longer auto-imported, `unhead.legacy` is ignored, Unhead's legacy plugins are no longer registered and Capo sorting is always on
+- **PostCSS defaults off**: `autoprefixer` and `cssnano` are no longer configured unless you enable them in `postcss.plugins`
+- **Keyed composables require `source`**: a [`optimization.keyedComposables`](/docs/api/nuxt-config#keyedcomposables) entry without a string `source` is no longer matched through its auto-import
 - **Comment node placeholders**: client-only components use [comment nodes instead of `<div>`](/docs/guide/going-further/experimental-features#clientnodeplaceholder) as SSR placeholders
 - **Typed pages**: [`experimental.typedPages`](/docs/guide/going-further/experimental-features#typedpages) is enabled for type-checked routing
 - **Typed `$fetch`**: [`experimental.routeTypedFetch`](/docs/guide/going-further/experimental-features#routetypedfetch) types `$fetch` and `useFetch` from the generated route types

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

@@ -127,17 +127,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 `nitro2` file | In a `nitro3` file |
 | --- | --- | --- |
 | Storage: `useStorage()` and its driver configuration | `nitropack/runtime` | `nitro/storage` |
-| Sessions: `useSession`, `getSession`, `updateSession`, `clearSession` | `h3` | `nitro/h3` |
 | Caching: `defineCachedEventHandler()`, `defineCachedFunction()` | `nitropack/runtime` | `nitro/cache` |
+| Server plugins | `defineNitroPlugin()` from `nitropack/runtime` | `definePlugin()` from `nitro` |
+| Runtime hooks, including `render:html` | `useNitroApp().hooks` from `nitropack/runtime` | `useNitroHooks()` from `nitro/app` |
+| App-relative fetch | `useNitroApp().localFetch` from `nitropack/runtime` | `serverFetch()` from `nitro` |
+| Lazy handlers: `lazyEventHandler()` | `h3` | `nitro/h3` |
 
-Nitro's runtime hooks (`useNitroApp().hooks`, including `render:html`) and tasks are 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 are not auto-imported from `nuxt/server`. In server code, the [auto-imported](/docs/directory-structure/server) names of the same spelling are h3's own helpers, which take the h3 event and behave differently in places (`defineEventHandler`, `handleCors`, `getRouterParams` and `readValidatedBody` among them), so import from `nuxt/server` explicitly. That includes `defineEventHandler`: the `nuxt/server` helpers read the event it hands the handler.
 
 ::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` 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 v1'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,38 +153,37 @@ Most of those helpers take the event as it is:
 
 ```ts [server/api/upload.post.ts]
 import { defineEventHandler, toNuxtRequestEvent } from 'nuxt/server'
-import { readValidatedBody } from 'h3'
+import { readMultipartFormData } from 'h3'
 
 export default defineEventHandler(async (event) => {
-  const body = await readValidatedBody(toNuxtRequestEvent(event), schema)
-  return { received: body }
+  const parts = await readMultipartFormData(toNuxtRequestEvent(event))
+  return { received: parts?.length ?? 0 }
 })
 ```
 
-Under `@nuxt/nitro-server` the event a handler receives is a view of the h3 v1 event, so `toNuxtRequestEvent(event)` is what h3's own helpers take: `readValidatedBody`, `getValidatedQuery`, `getRouterParam`, `getRouterParams`, `getRequestIP`, `assertMethod`, the session helpers, the CORS helpers (such as `handleCors`), `proxy`, `proxyRequest`, `fetchWithEvent` and `writeEarlyHints`, as well as reading `event.node` or `event.waitUntil()`.
+Under `@nuxt/nitro-server` the event a handler receives is a view of the h3 v1 event, so `toNuxtRequestEvent(event)` is what h3's own helpers take: `readRawBody`, `readFormData`, `readMultipartFormData`, `assertMethod`, `proxy`, `proxyRequest`, `fetchWithEvent` and `writeEarlyHints`, as well as reading `event.node` or `event.waitUntil()`.
 
 Nitro's own APIs mostly take no event at all: `defineCachedEventHandler()`, `useStorage()`, `useDatabase()` and tasks.
 
 ::tip
 If you find you are writing Nitro-specific code, you may simply prefer to import `defineEventHandler` from `h3` instead:
 
-```ts [server/api/cors.ts]
-import { defineEventHandler, handleCors } from 'h3'
+```ts [server/api/proxy.ts]
+import { defineEventHandler, proxyRequest } from '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 `nitropack/runtime`, and so does the driver configuration behind it.
-- **Sessions.** The sealed-session helpers come from `h3`. They accept the runtime's event, but importing them pins the file to Nitro.
-- **Caching.** `defineCachedEventHandler()` and `defineCachedFunction()` come from `nitropack/runtime`.
+- **Caching.** `defineCachedEventHandler()` and `defineCachedFunction()` come from `nitropack/runtime`. For caching that runs anywhere, depend on a cache library directly.
+- **Server plugins and hooks.** `defineNitroPlugin()` and the runtime hooks (`useNitroApp().hooks`, including `render:html`) come from `nitropack/runtime`.
+- **App-relative fetch.** `useNitroApp().localFetch` comes from `nitropack/runtime`. It calls a route of the app without an origin, which needs the runtime's router.
+- **Lazy handlers.** `lazyEventHandler()` comes from `h3`.
 
 ## Server Code Only
 

package/4.api/6.nuxt-config.md

@@ -1605,6 +1605,17 @@ If set to true, this will type check in development. You can restrict this to bu
 
 **See**: [Nuxt TypeScript docs](/docs/guide/concepts/typescript)
 
+## typesDir
+
+Define the directory where generated types and `tsconfig.json` files will be placed.
+
+This defaults to your `buildDir`, and is separate from it so that the configurations referenced by your project `tsconfig.json` stay in place even when Nuxt builds elsewhere (as it does when building a project that has already been run in development).
+
+If a relative path is specified, it will be relative to your `rootDir`.
+
+- **Type**: `string`
+- **Default:** `"/<rootDir>/.nuxt"`
+
 ## unhead
 
 An object that allows us to configure the `unhead` nuxt module.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.6.0-29837544.9d4d1eda",
+  "version": "4.6.0-29838870.2da76d24",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",