@nuxt/docs-nightly 4.6.0-29833429.e2a0e5da → 4.6.0-29836601.d5e5f1bd

package/1.getting-started/13.server.md

@@ -63,7 +63,7 @@ Or for other runtimes:
 
 ## Hybrid Rendering
 
-Nitro has a powerful feature called `routeRules` which allows you to define a set of rules to customize how each route of your Nuxt app is rendered (and more).
+Nuxt has a powerful feature called `routeRules` which allows you to define a set of rules to customize how each route of your Nuxt app is rendered (and more). Nuxt compiles the rules, and the default server builder (Nitro) applies the server-side ones.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({

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

@@ -1322,6 +1322,12 @@ If an error occurs during streaming after the HTTP status is already committed,
 **Route styles are streamed, JS hints are entry-only.** The shell is flushed before the route renders, so its `<head>` carries entry-chunk styles and hints only. Once render registers the page and layout modules, their CSS is streamed straight after the shell (inlined as `<style>` when `inlineStyles` is enabled, otherwise as stylesheet links), so page, layout, and top-level async-component styles arrive before the body paints (nested async components are a FOUC caveat, covered below). Route-specific JS chunks are not preloaded from the shell; the browser discovers them after parsing the entry script. Streaming improves TTFB on every route; LCP gains are largest on routes whose JS overlaps the entry chunk.
 ::
 
+::warning
+**Head tags registered after the shell flushes become client-side patches.** The renderer waits for the first render pass before flushing the shell, so `useHead`/`useSeoMeta` called synchronously in `<script setup>` (before any `await`), in plugins, or in middleware render into the shell `<head>` as usual. Tags registered later (after an `await` in setup, or inside a nested `<Suspense>` boundary) cannot reach the already-sent `<head>`; they are delivered as inline scripts that patch the DOM on the client.
+
+Clients that run JavaScript apply the patch, and clients matching `botRegex` never stream in the first place, so they receive the full buffered `<head>`. Anything else (a crawler your `botRegex` does not list, a link unfurler, `curl`) will not see those tags at all. JSON-LD scripts, `noscript` tags and body-positioned tags are the exception: they are rendered as real markup before `</body>`, where every client can read them. Keep other SEO-critical tags (canonical links, social meta) synchronous, or opt the route out of streaming with `routeRules: { '/path': { streaming: false } }`.
+::
+
 ::note
 **Component islands are compatible with streaming.** Island slot content and selective-client (`nuxt-client`) components are normally stitched into the HTML in a post-render pass, which is impossible once the body has streamed past the island anchors. Instead, the renderer emits each island teleport as an inert `<template>` at the end of the document and relocates it into place with an inline script that runs before hydration. This is transparent to app code. The exception is apps built with `features.noScripts` and island components, which fall back to the buffered renderer since the relocation script cannot run.
 ::

package/3.guide/6.going-further/10.runtime-config.md

@@ -33,6 +33,28 @@ console.log(runtimeConfig.public.apiBase)
 Public runtime config is accessible in Vue templates with `$config.public`.
 ::
 
+### Application Secret
+
+Runtime config keys prefixed with `app` are reserved for Nuxt (currently `runtimeConfig.app` and `runtimeConfig.appSecret`). Do not use them for your own values.
+
+Nuxt provides a private `runtimeConfig.appSecret` as the application's root secret. Modules and server features derive their own secrets from it with [`deriveSecret`](/docs/guide/going-further/server-imports#deriving-secrets), and the [session helpers](/docs/guide/going-further/server-imports#sessions) seal with one by default. The value defaults to an empty string, is only available on the server, and you can set it with `NUXT_APP_SECRET` without declaring the key in `nuxt.config`.
+
+Generate a secret that contains at least 32 random bytes:
+
+```bash [Terminal]
+openssl rand -base64 32
+```
+
+::important
+Use a different value for each environment, but keep it stable across deployments and server instances within that environment. Changing the value invalidates any sessions or signatures that depend on it.
+::
+
+Nitro parses environment overrides, so a secret made only of digits or one that looks like JSON arrives as a number, boolean or object rather than a string. Wrap such a value in quotes (`NUXT_APP_SECRET='"12345..."'`) or set `runtimeConfig.appSecret` in `nuxt.config` instead.
+
+In development, Nuxt generates a random secret and stores it in `.nuxt/app-secret` only when `appSecret` is unset, so features that depend on it work without any setup. A configured value is always used as is. Nuxt logs a warning the first time a derived secret is used with the generated value. Builds never generate one: set `NUXT_APP_SECRET` in every environment you deploy to.
+
+Nuxt does not require `NUXT_APP_SECRET` unless a module or server feature uses it.
+
 ### Serialization
 
 Your runtime config will be serialized before being passed to Nitro. This means that anything that cannot be serialized and then deserialized (such as functions, Sets, Maps, and so on), should not be set in your `nuxt.config`.
@@ -52,7 +74,7 @@ Runtime config values are **automatically replaced by matching environment varia
 
 There are two key requirements:
 
-1. Your desired variables must be defined in your `nuxt.config`. This ensures that arbitrary environment variables are not exposed to your application code.
+1. Custom runtime config variables must be defined in your `nuxt.config`. This ensures that arbitrary environment variables are not exposed to your application code.
 
 1. Only a specially-named environment variable can override a runtime config property. That is, an uppercase environment variable starting with `NUXT_` which uses `_` to separate keys and case changes.
 

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

@@ -42,11 +42,13 @@ This code can run under `@nuxt/nitro-server` and under `@nuxt/vite-server`, and
 | `setResponseStatus` | Set the response status and reason phrase. |
 | `setResponseHeader`, `setResponseHeaders` | Set response headers. |
 | `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). |
 | `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` and `NuxtErrorLike`.
+Types are exported alongside the utilities: `RequestEvent`, `RequestEventContext`, `NuxtRequestEvent`, `EventHandler`, `AppRouteRules`, `ServerRoutes`, `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.
 
@@ -78,6 +80,44 @@ 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)`.
 
+## 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: '/'`.
+
+```ts [server/api/visits.ts]
+import { defineEventHandler, useSession } from 'nuxt/server'
+
+export default defineEventHandler(async (event) => {
+  const session = await useSession<{ visits: number }>(event)
+  await session.update(data => ({ visits: (data.visits ?? 0) + 1 }))
+  return { visits: session.data.visits }
+})
+```
+
+With no `password`, the session is sealed with a secret derived from the application's [`appSecret`](/docs/guide/going-further/runtime-config#application-secret), so `NUXT_APP_SECRET` is the only thing to set. Pass a `password` of at least 32 characters to seal with a secret of your own instead. Set `maxAge` (in seconds) to expire both the cookie and the sealed value, `name` to change the cookie name from `nuxt-session`, and `cookie` to override any cookie attribute.
+
+The session is unsealed once per request, so `getSession` may be called from as many places as you like. `updateSession` and `clearSession` are the same operations without the manager object.
+
+### Deriving Secrets
+
+`deriveSecret(purpose)` resolves a secret for one purpose from `appSecret`: 32 bytes, hex-encoded, stable for as long as `appSecret` is unchanged, and distinct for every purpose. It is what the session helpers use, and what a module should use in place of asking for a secret of its own. Namespace the purpose to what owns it.
+
+```ts
+import { deriveSecret } from 'nuxt/server'
+
+const password = await deriveSecret('my-module:tokens')
+```
+
+It throws a `500` naming `NUXT_APP_SECRET` when `appSecret` is unset or shorter than 32 characters.
+
+::note
+h3 ships session helpers of the same names, and under `@nuxt/nitro-server` those are what the auto-imported `useSession`, `getSession`, `updateSession` and `clearSession` resolve to, so import these from `nuxt/server` explicitly. They are a separate implementation and are not interchangeable: h3 defaults to the `h3` cookie name rather than `nuxt-session`, takes its own configuration, and a session one of them issues will not unseal with the other.
+::
+
+::warning
+The session travels in the cookie, so it is limited to what a browser will accept. Writing a session that serialises to more than 4096 bytes throws; keep large data server-side and reference it from the session by id.
+::
+
 ## Reaching Past the Surface
 
 `nuxt/server` isn't a re-export of h3, so if you need something else that h3 and Nitro offer, such as the server lifecycle (`defineNitroPlugin`, `defineNitroErrorHandler` and the Nitro app hooks), you would import it directly.

package/4.api/3.utils/prerender-routes.md

@@ -1,6 +1,6 @@
 ---
 title: 'prerenderRoutes'
-description: prerenderRoutes hints to Nitro to prerender an additional route.
+description: prerenderRoutes hints that an additional route should be prerendered.
 minimalVersion: "3.8"
 links:
   - label: Source
@@ -9,7 +9,7 @@ links:
     size: xs
 ---
 
-When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page.
+When prerendering, you can hint that additional paths should be prerendered, even if their URLs do not show up in the HTML of the generated page. Nuxt collects the hints and passes them to your server builder's prerenderer (Nitro by default).
 
 ::important
 `prerenderRoutes` can only be called within the [Nuxt context](/docs/guide/going-further/nuxt-app#the-nuxt-context).

package/4.api/5.kit/12.nitro.md

@@ -34,7 +34,7 @@ export default defineNuxtModule({
 ### Type
 
 ```ts
-function addServerHandler (handler: NitroEventHandler): void
+function addServerHandler (handler: ServerHandlerInput): void
 ```
 
 ### Parameters
@@ -43,12 +43,18 @@ function addServerHandler (handler: NitroEventHandler): void
 
 | Property     | Type      | Required | Description                                                                                                                                   |
 |--------------|-----------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|
-| `handler`    | `string`  | `true`   | Path to event handler.                                                                                                                        |
-| `route`      | `string`  | `false`  | Path prefix or route. If an empty string used, will be used as a middleware.                                                                  |
+| `handler`    | `string \| { nuxt?: string, nitro2?: string, nitro3?: string }`  | `true`   | Path to the event handler, or one path per server API. Nuxt registers the implementation the application's server can run.                     |
+| `route`      | `string`  | `false`  | The route to match, exactly. End it in `/**` to match the paths below it as well. If an empty string is used, the handler is registered as middleware. |
 | `middleware` | `boolean` | `false`  | Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers. |
 | `lazy`       | `boolean` | `false`  | Use lazy loading to import the handler. This is useful when you only want to load the handler on demand.                                      |
 | `method`     | `string`  | `false`  | Router method matcher. If handler name contains method name, it will be used as a default value.                                              |
 
+A route ending in `/**` matches its base path too, so `route: '/_fonts/**'` serves `/_fonts` and everything below it. On a Nitro 2 host, whose router matches only the paths below the base, Nuxt registers the base path as a second route so that one registration behaves the same on both.
+
+::read-more{to="/docs/guide/modules/server-compatibility"}
+Learn when to register one path per server API, and which key to write your handler against.
+::
+
 ### Example
 
 #### Basic Usage
@@ -115,11 +121,8 @@ export default defineNuxtModule({
 
 ### Type
 
-```ts twoslash
-// @errors: 2391
-import type { NitroDevEventHandler } from 'nitropack/types'
-// ---cut---
-function addDevServerHandler (handler: NitroDevEventHandler): void
+```ts
+function addDevServerHandler (handler: DevServerHandlerInput): void
 ```
 
 ### Parameters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.6.0-29833429.e2a0e5da",
+  "version": "4.6.0-29836601.d5e5f1bd",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",