@nuxt/docs-nightly 4.5.1-29752449.30d24817 → 4.5.2-2610052030-052d82e

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

@@ -5,7 +5,7 @@ description: "Nuxt provides a runtime config API to expose configuration and sec
 
 ## Exposing
 
-To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) option.
+To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/api/nuxt-config#runtimeconfig) option.
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -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`.
@@ -45,14 +67,14 @@ The most common way to provide configuration is by using environment variables.
 
 ::note
 The Nuxt CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.
-:read-more{to="/docs/4.x/directory-structure/env"}
+:read-more{to="/docs/directory-structure/env"}
 ::
 
 Runtime config values are **automatically replaced by matching environment variables at runtime**.
 
 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.
 
@@ -91,7 +113,7 @@ export default defineNuxtConfig({
 
 ### Vue App
 
-Within the Vue part of your Nuxt app, you will need to call [`useRuntimeConfig()`](/docs/4.x/api/composables/use-runtime-config) to access the runtime config.
+Within the Vue part of your Nuxt app, you will need to call [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) to access the runtime config.
 
 ::important
 The behavior is different between the client-side and server-side:
@@ -124,7 +146,7 @@ if (import.meta.server) {
 
 ### Plugins
 
-If you want to use the runtime config within any (custom) plugin, you can use [`useRuntimeConfig()`](/docs/4.x/api/composables/use-runtime-config) inside of your `defineNuxtPlugin` function.
+If you want to use the runtime config within any (custom) plugin, you can use [`useRuntimeConfig()`](/docs/api/composables/use-runtime-config) inside of your `defineNuxtPlugin` function.
 
 ```ts [app/plugins/config.ts]
 export default defineNuxtPlugin((nuxtApp) => {
@@ -151,7 +173,7 @@ export default defineEventHandler(async (event) => {
 ```
 
 ::note
-Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/4.x/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
+Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/guide/going-further/runtime-config#environment-variables) at runtime for server routes.
 ::
 
 ## Typing Runtime Config

package/3.guide/6.going-further/11.nightly-release-channel.md

@@ -57,6 +57,6 @@ To try the latest version of [nuxt/cli](https://github.com/nuxt/cli):
 npx @nuxt/cli-nightly@latest [command]
 ```
 
-::read-more{to="/docs/4.x/api/commands"}
+::read-more{to="/docs/api/commands"}
 Read more about the available commands.
 ::

package/3.guide/6.going-further/2.hooks.md

@@ -9,7 +9,7 @@ The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookabl
 
 ## Nuxt Hooks (Build Time)
 
-These hooks are available for [Nuxt modules](/docs/4.x/guide/modules) and build context.
+These hooks are available for [Nuxt modules](/docs/guide/modules) and build context.
 
 ### Within `nuxt.config.ts`
 
@@ -33,13 +33,13 @@ export default defineNuxtModule({
 })
 ```
 
-::read-more{to="/docs/4.x/api/advanced/hooks#nuxt-hooks-build-time"}
+::read-more{to="/docs/api/advanced/hooks#nuxt-hooks-build-time"}
 Explore all available Nuxt hooks.
 ::
 
 ## App Hooks (Runtime)
 
-App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
+App hooks can be mainly used by [Nuxt Plugins](/docs/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
 
 ```ts [app/plugins/test.ts]
 export default defineNuxtPlugin((nuxtApp) => {
@@ -49,13 +49,13 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-::read-more{to="/docs/4.x/api/advanced/hooks#app-hooks-runtime"}
+::read-more{to="/docs/api/advanced/hooks#app-hooks-runtime"}
 Explore all available App hooks.
 ::
 
 ## Server Hooks (Runtime)
 
-These hooks are available for [server plugins](/docs/4.x/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
+These hooks are available for [server plugins](/docs/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
 
 ```ts [~~/server/plugins/test.ts]
 export default defineNitroPlugin((nitroApp) => {
@@ -70,7 +70,7 @@ export default defineNitroPlugin((nitroApp) => {
 })
 ```
 
-::read-more{to="/docs/4.x/api/advanced/hooks#nitro-app-hooks-runtime-server-side"}
+::read-more{to="/docs/api/advanced/hooks#nitro-app-hooks-runtime-server-side"}
 Learn more about available Nitro lifecycle hooks.
 ::
 

package/3.guide/6.going-further/4.kit.md

@@ -3,9 +3,9 @@ title: "Nuxt Kit"
 description: "@nuxt/kit provides features for module authors."
 ---
 
-Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt modules](/docs/4.x/guide/modules) super easy.
+Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/api/advanced/hooks), the [Nuxt Interface](/docs/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt modules](/docs/guide/modules) super easy.
 
-::read-more{to="/docs/4.x/api/kit"}
+::read-more{to="/docs/api/kit"}
 Discover all Nuxt Kit utilities.
 ::
 
@@ -33,13 +33,13 @@ You can install the latest Nuxt Kit by adding it to the `dependencies` section o
 import { useNuxt } from '@nuxt/kit'
 ```
 
-:read-more{to="/docs/4.x/api/kit"}
+:read-more{to="/docs/api/kit"}
 
 ::note
 Nuxt Kit utilities are only available for modules and not meant to be imported in runtime (components, Vue composables, pages, plugins, or server routes).
 ::
 
-Nuxt Kit is an [esm-only package](/docs/4.x/guide/concepts/esm) meaning that you **cannot** `require('@nuxt/kit')`. As a workaround, use dynamic import in the CommonJS context:
+Nuxt Kit is an [esm-only package](/docs/guide/concepts/esm) meaning that you **cannot** `require('@nuxt/kit')`. As a workaround, use dynamic import in the CommonJS context:
 
 ```ts [test.cjs]
 // This does NOT work!

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

@@ -0,0 +1,221 @@
+---
+title: "Server Imports"
+description: "`nuxt/server` is the import surface for server code that isn't tied to a particular server runtime."
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/server/index.ts
+---
+
+It's possible to use different [server builders](/docs/guide/going-further/builders) with Nuxt: Nitro 2 (`nitropack`, the default in Nuxt 3 and 4), Nitro 3 (`nitro`, from Nuxt 5), or Vite directly.
+
+`nuxt/server` exists to provide agnostic utilities for server code that aren't tied to a particular server runtime. It is the second runtime surface of Nuxt, alongside `nuxt/app` (also reachable as `#app`), which is for the part of your application that also runs in the browser.
+
+```ts [server/api/hello.ts]
+import { defineEventHandler, getQuery } from 'nuxt/server'
+
+export default defineEventHandler((event) => {
+  const { name } = getQuery<{ name?: string }>(event)
+  return { message: `Hello, ${name ?? 'world'}!` }
+})
+```
+
+This code can run under `@nuxt/nitro-server` and under `@nuxt/vite-server`, and will also keep running across an h3 or Nitro major, because Nuxt absorbs those changes centrally.
+
+`nuxt/server` ships from Nuxt 4.6, so one file can serve Nuxt 4.6 running `nitropack` v2, Nuxt 5 running Nitro v3, and anything a future builder brings.
+
+::tip
+`nuxt` is installed in every Nuxt application, so `nuxt/server` resolves with no alias and no added dependency. A module importing from it needs no peer dependency on h3 or Nitro.
+::
+
+## Types and Utilities
+
+| Import | Purpose |
+|---|---|
+| `defineEventHandler` | Define a request handler. |
+| `createError`, `isNuxtError` | Construct and recognise an HTTP error. |
+| `getRequestURL`, `getRequestHost`, `getRequestProtocol` | The URL, host and protocol of the request. Pass `{ xForwardedHost: true, xForwardedProto: true }` to trust those headers, only behind a proxy you control that overwrites them. |
+| `getRequestHeader`, `getRequestHeaders` | Read request headers. |
+| `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`, `parseCookies`, `setCookie`, `deleteCookie` | Read one or every cookie, and write cookies. |
+| `setResponseStatus` | Set the response status and reason phrase. |
+| `handleCors` | Apply [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) headers and answer preflight requests. |
+| `sendRedirect` | Redirect the request. |
+| `serverFetch` | Fetch a route of the app in-process, with the path relative to `app.baseURL` and the `cookie` and `authorization` headers forwarded unless `forwardHeaders` is set. It rejects on a server builder without an in-process fetch. |
+| `useSession`, `getSession`, `updateSession`, `clearSession` | Read and write a [sealed session cookie](#sessions). |
+| `deriveSecret` | A purpose-specific secret [derived from `appSecret`](#deriving-secrets). |
+| `getRouteRules`, `matchRouteRules` | The [route rules](/docs/guide/concepts/rendering#route-rules) matched for the request, or for another path. |
+| `useRuntimeConfig` | The server's [runtime configuration](/docs/guide/going-further/runtime-config). |
+| `useServerHooks` | The server's runtime hooks: renderer hooks such as `render:html`, and those declared on `NuxtServerHooks`. |
+| `useAppConfig` | The [app config](/docs/directory-structure/app/app-config), as a copy per request when passed the event. |
+
+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 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.
+
+::read-more{to="/docs/getting-started/upgrade#moving-to-nuxtserver"}
+Moving existing server code to `nuxt/server`, and how its helpers differ from h3's.
+::
+
+::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.
+::
+
+## The Event
+
+`RequestEvent` is the event that `nuxt/server` utilities operate from, including the request, its URL, the response to be sent, and the request context.
+
+```ts
+interface RequestEvent {
+  readonly req: Request
+  url: URL
+  readonly res: { status?: number, statusText?: string, readonly headers: Headers }
+  readonly context: RequestEventContext
+}
+```
+
+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]
+export default defineEventHandler(async (event) => {
+  const { id } = await event.req.json()
+  return { id, page: event.url.searchParams.get('page') }
+})
+```
+
+`NuxtRequestEvent` is the same request in the shape the configured builder provides, which is h3 v1's `H3Event` under `@nuxt/nitro-server`.
+
+## Handlers
+
+A handler file must default-export the result of `defineEventHandler` from `nuxt/server`. A bare function, or one wrapped by h3's `defineEventHandler`, receives the server runtime's own event instead.
+
+A handler may return:
+
+- A JSON-serializable value, sent as JSON with the status and headers set on `event.res`.
+- A `Response`, sent with its own status. Headers set on `event.res.headers` are sent with it, and `set-cookie` values from both are kept.
+- A `ReadableStream`, streamed as the body.
+
+## 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: '/'`.
+
+```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.
+::
+
+::note
+The session API is stable, but the format of the sealed cookie may change in a minor release: Nuxt plans to move to an AES-GCM based seal once `iron-webcrypto` publishes one. When it does, existing sessions are read in the old format and resealed in the new one on their next write, so users are not signed out. Sealed values are not interchangeable with those from h3's `useSession`.
+::
+
+::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` and `defineNitroErrorHandler`) or Nitro's own runtime hooks, you would import it directly.
+
+For a handler that needs h3's own helpers, such as `readRawBody`, `readMultipartFormData`, `assertMethod`, `proxyRequest`, `fetchWithEvent` or `writeEarlyHints`, or that reads `event.node` or `event.waitUntil()`, import `defineEventHandler` from `h3` for that handler:
+
+```ts [server/api/upload.post.ts]
+import { defineEventHandler, readMultipartFormData } from 'h3'
+
+export default defineEventHandler(async (event) => {
+  const parts = await readMultipartFormData(event)
+  return { received: parts?.length ?? 0 }
+})
+```
+
+Nitro's own APIs mostly take no event at all: `defineCachedEventHandler()`, `useStorage()`, `useDatabase()` and tasks. Import them from `nitropack/runtime`.
+
+## What Isn't Portable
+
+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.
+- **Caching.** `defineCachedEventHandler()` and `defineCachedFunction()` come from `nitropack/runtime`. For caching that runs anywhere, depend on a cache library directly.
+- **Server plugins.** `defineNitroPlugin()` comes from `nitropack/runtime`. Inside a plugin, `useServerHooks()` from `nuxt/server` registers the renderer hooks (including `render:html`) and those declared on `NuxtServerHooks`; Nitro's own hooks, such as `request`, `beforeResponse` and `error`, come from `useNitroApp().hooks` in `nitropack/runtime`.
+- **Lazy handlers.** `lazyEventHandler()` comes from `h3`.
+
+## Server Code Only
+
+Importing `nuxt/server` from a Vue component, a plugin or the `shared/` directory fails the build, and the error points you at `#app`, `#imports`, `$fetch` and `useFetch` instead. Its types still resolve in those contexts, which is what lets `$fetch` know what your server routes return.
+
+## Modules
+
+A module whose runtime code imports only from `nuxt/server` runs under any server builder from v4.6 onwards, with no version check and no dependency on h3 or Nitro:
+
+```ts [runtime/server/api/status.ts]
+import { defineEventHandler, useRuntimeConfig } from 'nuxt/server'
+
+export default defineEventHandler(() => ({
+  version: useRuntimeConfig().myModule.version,
+}))
+```
+
+::tip
+Leave `nuxt/server` external when you bundle; it will be resolved in the Nuxt build to the right server builder utilities.
+::
+
+Supporting Nuxt versions <4.6 takes one more step, because those projects have no `nuxt/server` to resolve. You can instead register the portable file and the one you ship today side by side, and Nuxt will pick whichever the application can run.
+
+::read-more{to="/docs/guide/modules/server-compatibility"}
+See how to register one handler per server API.
+::
+
+::read-more{to="/docs/guide/going-further/builders"}
+Learn how a server builder supplies the implementations behind `nuxt/server`.
+::

package/3.guide/6.going-further/6.nuxt-app.md

@@ -15,7 +15,7 @@ In Nuxt 2, this was referred to as **Nuxt context**.
 
 ## Nuxt App Interface
 
-::read-more{to="/docs/4.x/guide/going-further/internals#the-nuxtapp-interface"}
+::read-more{to="/docs/guide/going-further/internals#the-nuxtapp-interface"}
 Jump over the `NuxtApp` interface documentation.
 ::
 
@@ -23,13 +23,13 @@ Jump over the `NuxtApp` interface documentation.
 
 Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
 
-Currently, the Nuxt context is only accessible in [plugins](/docs/4.x/directory-structure/app/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup) (in pages and components).
+Currently, the Nuxt context is only accessible in [plugins](/docs/directory-structure/app/plugins), [Nuxt hooks](/docs/guide/going-further/hooks), [Nuxt middleware](/docs/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup) (in pages and components).
 
-If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/4.x/api/composables/use-nuxt-app#runwithcontext).
+If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/api/composables/use-nuxt-app#runwithcontext).
 
 ## Accessing NuxtApp
 
-Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/4.x/api/composables/use-nuxt-app):
+Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/api/composables/use-nuxt-app):
 
 ```ts [app/composables/useMyComposable.ts]
 export function useMyComposable () {
@@ -38,11 +38,11 @@ export function useMyComposable () {
 }
 ```
 
-If your composable does not always need `nuxtApp` or you simply want to check if it is present or not, since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead.
+If your composable does not always need `nuxtApp` or you simply want to check if it is present or not, since [`useNuxtApp`](/docs/api/composables/use-nuxt-app) throws an exception, you can use [`tryUseNuxtApp`](/docs/api/composables/use-nuxt-app#tryusenuxtapp) instead.
 
 Plugins also receive `nuxtApp` as the first argument for convenience.
 
-:read-more{to="/docs/4.x/directory-structure/app/plugins"}
+:read-more{to="/docs/directory-structure/app/plugins"}
 
 ## Providing Helpers
 
@@ -55,7 +55,7 @@ nuxtApp.provide('hello', name => `Hello ${name}!`)
 console.log(nuxtApp.$hello('name')) // Prints "Hello name!"
 ```
 
-::read-more{to="/docs/4.x/directory-structure/app/plugins#providing-helpers"}
+::read-more{to="/docs/directory-structure/app/plugins#providing-helpers"}
 It is possible to inject helpers by returning an object with a `provide` key in plugins.
 ::
 

package/3.guide/6.going-further/7.layers.md

@@ -5,9 +5,9 @@ description: Nuxt provides a powerful system that allows you to extend the defau
 
 Nuxt layers are a powerful feature that you can use to share and reuse partial Nuxt applications within a monorepo, or from a git repository or npm package. The layers structure is almost identical to a standard Nuxt application, which makes them easy to author and maintain.
 
-:read-more{to="/docs/4.x/getting-started/layers"}
+:read-more{to="/docs/getting-started/layers"}
 
-A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file to indicate it is a layer.
+A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/directory-structure/nuxt-config) file to indicate it is a layer.
 
 ```ts [base/nuxt.config.ts]
 export default defineNuxtConfig({})
@@ -15,16 +15,16 @@ export default defineNuxtConfig({})
 
 Additionally, certain other files in the layer directory will be auto-scanned and used by Nuxt for the project extending this layer.
 
-- [`app/components/*`](/docs/4.x/directory-structure/app/components)   - Extend the default components
-- [`app/composables/*`](/docs/4.x/directory-structure/app/composables)  - Extend the default composables
-- [`app/layouts/*`](/docs/4.x/directory-structure/app/layouts)  - Extend the default layouts
-- [`app/middleware/*`](/docs/4.x/directory-structure/app/middleware)  - Extend the default middleware
-- [`app/pages/*`](/docs/4.x/directory-structure/app/pages)        - Extend the default pages
-- [`app/plugins/*`](/docs/4.x/directory-structure/app/plugins)        - Extend the default plugins
-- [`app/utils/*`](/docs/4.x/directory-structure/app/utils)   - Extend the default utils
-- [`app/app.config.ts`](/docs/4.x/directory-structure/app/app-config)  - Extend the default app config
-- [`server/*`](/docs/4.x/directory-structure/server)       - Extend the default server endpoints & middleware
-- [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config)- Extend the default nuxt config
+- [`app/components/*`](/docs/directory-structure/app/components)   - Extend the default components
+- [`app/composables/*`](/docs/directory-structure/app/composables)  - Extend the default composables
+- [`app/layouts/*`](/docs/directory-structure/app/layouts)  - Extend the default layouts
+- [`app/middleware/*`](/docs/directory-structure/app/middleware)  - Extend the default middleware
+- [`app/pages/*`](/docs/directory-structure/app/pages)        - Extend the default pages
+- [`app/plugins/*`](/docs/directory-structure/app/plugins)        - Extend the default plugins
+- [`app/utils/*`](/docs/directory-structure/app/utils)   - Extend the default utils
+- [`app/app.config.ts`](/docs/directory-structure/app/app-config)  - Extend the default app config
+- [`server/*`](/docs/directory-structure/server)       - Extend the default server endpoints & middleware
+- [`nuxt.config.ts`](/docs/directory-structure/nuxt-config)- Extend the default nuxt config
 
 ## Basic Example
 
@@ -283,7 +283,7 @@ You can also use this approach to disable modules in your own project - not just
 
 ## Multi-Layer Support for Nuxt Modules
 
-You can use the [`getLayerDirectories`](/docs/4.x/api/kit/layers#getlayerdirectories) utility from Nuxt Kit to support custom multi-layer handling for your modules.
+You can use the [`getLayerDirectories`](/docs/api/kit/layers#getlayerdirectories) utility from Nuxt Kit to support custom multi-layer handling for your modules.
 
 ```ts [modules/my-module.ts]
 import { defineNuxtModule, getLayerDirectories } from 'nuxt/kit'

package/3.guide/6.going-further/8.builders.md

@@ -3,19 +3,19 @@ title: "Creating a Builder"
 description: "Learn how Nuxt builders work and how to author your own."
 ---
 
-A **builder** is the part of Nuxt responsible for bundling your application. Nuxt ships with three official builders, [Vite](https://vite.dev) (the default), [webpack](https://webpack.js.org) and [Rspack](https://rspack.dev), and you can select one with the [`builder`](/docs/4.x/api/nuxt-config#builder) option or supply your own.
+A **builder** is the part of Nuxt responsible for bundling your application. Nuxt ships with three official builders, [Vite](https://vite.dev) (the default), [webpack](https://webpack.js.org) and [Rspack](https://rspack.dev), and you can select one with the [`builder`](/docs/api/nuxt-config#builder) option or supply your own.
 
 This guide explains how builders fit into the Nuxt build, what contract a builder must fulfil, and how to author one.
 
 ::note
-Authoring a builder is an advanced topic. Most apps never need a custom builder; if you only want to influence the bundle, a [module](/docs/4.x/guide/modules) that registers bundler plugins is usually the right tool.
+Authoring a builder is an advanced topic. Most apps never need a custom builder; if you only want to influence the bundle, a [module](/docs/guide/modules) that registers bundler plugins is usually the right tool.
 ::
 
 ## What a Builder Does
 
 Nuxt separates **what** to build from **how** to build it.
 
-The Nuxt core (the `nuxt` context described in [How Nuxt Works](/docs/4.x/guide/going-further/internals)) and your modules generate the virtual application: the entrypoints, route table, plugins, component registry, and the rest of the [virtual file system](/docs/4.x/guide/going-further/internals#the-nuxt-interface) under `#build`. The builder takes that virtual application and turns it into real JavaScript and CSS bundles, and in development runs a dev server that serves and hot-reloads them.
+The Nuxt core (the `nuxt` context described in [How Nuxt Works](/docs/guide/going-further/internals)) and your modules generate the virtual application: the entrypoints, route table, plugins, component registry, and the rest of the [virtual file system](/docs/guide/going-further/internals#the-nuxt-interface) under `#build`. The builder takes that virtual application and turns it into real JavaScript and CSS bundles, and in development runs a dev server that serves and hot-reloads them.
 
 Concretely, a builder is responsible for:
 
@@ -44,7 +44,7 @@ export interface NuxtBuilder {
 }
 ```
 
-Nuxt resolves the active builder from the [`builder`](/docs/4.x/api/nuxt-config#builder) option. It accepts either a module specifier that default-exports a `NuxtBuilder`, or an inline object:
+Nuxt resolves the active builder from the [`builder`](/docs/api/nuxt-config#builder) option. It accepts either a module specifier that default-exports a `NuxtBuilder`, or an inline object:
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -75,7 +75,7 @@ Only the three official builder specifiers (`@nuxt/vite-builder`, `@nuxt/webpack
 
 ## The Build Lifecycle
 
-When you run [`nuxt build`](/docs/4.x/api/commands/build) or [`nuxt dev`](/docs/4.x/api/commands/dev), Nuxt:
+When you run [`nuxt build`](/docs/api/commands/build) or [`nuxt dev`](/docs/api/commands/dev), Nuxt:
 
 1. Creates the `nuxt` context and runs modules, populating `nuxt.options` and the build hooks.
 2. Generates the virtual application (templates, route table, plugins) into the `#build` virtual file system.
@@ -88,15 +88,15 @@ Your `bundle` implementation typically branches on `nuxt.options.dev`:
 - In **production**, it runs the client and (if `nuxt.options.ssr`) server builds to completion, writing artifacts to `nuxt.options.buildDir` and registering them as build outputs.
 - In **development**, it sets up a dev server, starts a watching build, assigns `nuxt.server`, and keeps running.
 
-A builder communicates with the rest of Nuxt almost entirely through [hooks](/docs/4.x/api/advanced/hooks). It reads build configuration off `nuxt.options` and, when appropriate, lets modules extend its bundler configuration.
+A builder communicates with the rest of Nuxt almost entirely through [hooks](/docs/api/advanced/hooks). It reads build configuration off `nuxt.options` and, when appropriate, lets modules extend its bundler configuration.
 
 ### Letting Modules Extend the Bundler
 
-Modules influence the bundle through [Nuxt Kit](/docs/4.x/guide/going-further/kit) helpers. A builder should honour the relevant ones:
+Modules influence the bundle through [Nuxt Kit](/docs/guide/going-further/kit) helpers. A builder should honour the relevant ones:
 
-- [`addVitePlugin`](/docs/4.x/api/kit/builder#addviteplugin) / [`addWebpackPlugin`](/docs/4.x/api/kit/builder#addwebpackplugin) register bundler-specific plugins.
-- [`addBuildPlugin`](/docs/4.x/api/kit/builder#addbuildplugin) registers an [unplugin](https://github.com/unjs/unplugin) factory, so a single plugin works across every builder.
-- [`extendViteConfig`](/docs/4.x/api/kit/builder#extendviteconfig) / [`extendWebpackConfig`](/docs/4.x/api/kit/builder#extendwebpackconfig) mutate the resolved bundler config.
+- [`addVitePlugin`](/docs/api/kit/builder#addviteplugin) / [`addWebpackPlugin`](/docs/api/kit/builder#addwebpackplugin) register bundler-specific plugins.
+- [`addBuildPlugin`](/docs/api/kit/builder#addbuildplugin) registers an [unplugin](https://github.com/unjs/unplugin) factory, so a single plugin works across every builder.
+- [`extendViteConfig`](/docs/api/kit/builder#extendviteconfig) / [`extendWebpackConfig`](/docs/api/kit/builder#extendwebpackconfig) mutate the resolved bundler config.
 
 The official builders also emit their own hooks (for example `vite:extendConfig`, `vite:serverCreated`, `webpack:config`) so modules and Nitro can participate in the build. A custom builder may emit its own hooks, but the build output contract below is what makes it interoperate with the Nuxt server runtime.
 
@@ -156,7 +156,7 @@ The keys come in two shapes:
 
 ### Setting Build Outputs
 
-Use the [`setBuildOutput`](/docs/4.x/api/kit/builder#setbuildoutput) helper from `@nuxt/kit`:
+Use the [`setBuildOutput`](/docs/api/kit/builder#setbuildoutput) helper from `@nuxt/kit`:
 
 ```ts
 import { setBuildOutput } from '@nuxt/kit'
@@ -164,7 +164,7 @@ import { setBuildOutput } from '@nuxt/kit'
 setBuildOutput('clientManifest', () => 'export default ' + serializedManifest)
 ```
 
-`setBuildOutput` writes to `nuxt.buildOutputs[key]`. From inside a bundler plugin that already holds the `nuxt` instance you can assign `nuxt.buildOutputs[key]` directly; `setBuildOutput` is the convenience for code that resolves `nuxt` via [`useNuxt()`](/docs/4.x/api/kit/context#usenuxt).
+`setBuildOutput` writes to `nuxt.buildOutputs[key]`. From inside a bundler plugin that already holds the `nuxt` instance you can assign `nuxt.buildOutputs[key]` directly; `setBuildOutput` is the convenience for code that resolves `nuxt` via [`useNuxt()`](/docs/api/kit/context#usenuxt).
 
 A provider can be asynchronous and is read lazily, when the server build resolves the corresponding `nuxt/*` import. This lets a builder register the provider early (for example before the client build has finished) and have it return the finalised value once the data exists.
 
@@ -211,10 +211,34 @@ In development, a builder is also responsible for serving and hot-reloading the
 
 In dev, the build outputs are typically wired to live, in-memory sources rather than on-disk files. For instance, the SSR entry may be served from the bundler's in-memory output, and the client manifest may be computed from the dev module graph, rather than read from `nuxt.options.buildDir`.
 
-::read-more{to="/docs/4.x/guide/going-further/internals"}
+## Describing the Build to a Deploy Target
+
+A server builder describes what it produced, so that tooling that deploys or previews the build does not have to know which builder ran. The description lives on `nuxt.serverBuild`, and is read with `useServerBuild()` from `@nuxt/kit/internal`:
+
+```ts
+import { useServerBuild } from '@nuxt/kit/internal'
+
+const build = useServerBuild()
+
+build.output.root() // the project root: where a target's own config file lives
+build.output.dir() // the build output directory
+build.output.publicDir() // the deployable static assets within it
+```
+
+Every path is a function, because a builder may only resolve it while initialising, so call them from a hook that runs after the server builder has run.
+
+The description also says how the server build relates to the app build. A server builder sets `buildsSeparately` to declare whether its build is a pass of its own, run after the app build (as `@nuxt/nitro-server` does), or whether the app builder is building everything and there is no separate pass (as with `@nuxt/vite-server`). Anything that needs to know reads it from the description rather than sniffing for a Nitro instance.
+
+`output.root()` is deliberately not a bundler root. Nuxt points Vite's `root` at [`srcDir`](/docs/api/nuxt-config#srcdir), so a deploy target that resolves its configuration file (or the paths written inside it) from the bundler's root looks inside your app directory rather than at the root of your project. A target that reads the description resolves both correctly.
+
+::warning
+`nuxt.serverBuild` and the `setServerBuild()` / `useServerBuild()` helpers are experimental and exported from `@nuxt/kit/internal`. The shape will change without a major release while a second server builder is being built out.
+::
+
+::read-more{to="/docs/guide/going-further/internals"}
 Learn more about the Nuxt interface and the build vs. runtime split.
 ::
 
-::read-more{to="/docs/4.x/api/kit/builder"}
+::read-more{to="/docs/api/kit/builder"}
 Browse the Nuxt Kit builder utilities used to register bundler plugins and build outputs.
 ::

package/4.api/1.components/1.nuxt-client-fallback.md

@@ -14,7 +14,7 @@ links:
 
 Nuxt provides the `<NuxtClientFallback>` component to render its content on the client if any of its children trigger an error in SSR.
 
-::note{to="/docs/4.x/guide/going-further/experimental-features#clientfallback"}
+::note{to="/docs/guide/going-further/experimental-features#clientfallback"}
 This component is experimental and in order to use it you must enable the `experimental.clientFallback` option in your `nuxt.config`.
 ::
 

package/4.api/1.components/10.nuxt-picture.md

@@ -10,7 +10,7 @@ links:
 
 `<NuxtPicture>` is a drop-in replacement for the native `<picture>` tag.
 
-Usage of `<NuxtPicture>` is almost identical to [`<NuxtImg>`](/docs/4.x/api/components/nuxt-img) but it also allows serving modern formats like `webp` when possible.
+Usage of `<NuxtPicture>` is almost identical to [`<NuxtImg>`](/docs/api/components/nuxt-img) but it also allows serving modern formats like `webp` when possible.
 
 Learn more about the [`<picture>` tag on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/picture).
 

package/4.api/1.components/11.teleports.md

@@ -40,4 +40,4 @@ The `to` target of [`<Teleport>`](https://vuejs.org/guide/built-ins/teleport) ex
 </template>
 ```
 
-:link-example{to="/docs/4.x/examples/advanced/teleport"}
+:link-example{to="/docs/examples/advanced/teleport"}