@nuxt/docs-nightly 5.0.0-29554472.d5d8ce2f → 5.0.0-29554612.0e08003b

package/1.getting-started/10.data-fetching.md

@@ -607,7 +607,6 @@ However, when calling `useFetch` with a relative URL on the server, Nuxt will us
  If you want to pass on/proxy cookies in the other direction, from an internal request back to the client, you will need to handle this yourself.
 
 ```ts [app/composables/fetch.ts]
-import { appendResponseHeader } from 'h3'
 import type { H3Event } from 'h3'
 
 export const fetchWithCookie = async (event: H3Event, url: string) => {
@@ -617,7 +616,7 @@ export const fetchWithCookie = async (event: H3Event, url: string) => {
   const cookies = res.headers.getSetCookie()
   /* Attach each cookie to our incoming Request */
   for (const cookie of cookies) {
-    appendResponseHeader(event, 'set-cookie', cookie)
+    event.res.headers.append('set-cookie', cookie)
   }
   /* Return the data of the response */
   return res._data

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

@@ -29,6 +29,8 @@ You can easily manage the server-only part of your Nuxt app, from API endpoints
 Both endpoints and middleware can be defined like this:
 
 ```ts twoslash [server/api/test.ts]
+import { defineEventHandler } from 'nitro/h3'
+
 export default defineEventHandler(async (event) => {
   // ... Do whatever you want here
 })
@@ -74,7 +76,7 @@ export default defineNuxtConfig({
     '/api/*': { cache: { maxAge: 60 * 60 } },
     // Redirection to avoid 404
     '/old-page': {
-      redirect: { to: '/new-page', statusCode: 302 },
+      redirect: { to: '/new-page', status: 302 },
     },
     // ...
   },

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

@@ -203,6 +203,151 @@ Most of the migration is handled by Nuxt internally, but there are some user-fac
 See the full Vite 8 migration guide for all breaking changes and migration steps.
 ::
 
+### Migration to Nitro v3
+
+🚦 **Impact Level**: Significant
+
+#### What Changed
+
+Nuxt 5 upgrades to [Nitro v3](https://nitro.build/blog/v3-beta), which is a major rewrite of the server engine. Nitro v3 is built on [srvx](https://srvx.h3.dev) and [h3 v2](https://h3.dev), adopting Web standard `Request`/`Response` APIs throughout. This brings performance improvements and a more consistent API, but includes several breaking changes to server-side code.
+
+::important
+We are still working on Nitro v3 integration so you should expect further changes, as well as additional work to make migration more straightforward.
+::
+
+::read-more{to="https://nitro.build/blog/v3-beta" target="_blank"}
+Read the Nitro v3 beta announcement for a full overview.
+::
+
+::read-more{to="https://nitro.build/docs/migration" target="_blank"}
+See the full Nitro v3 migration guide for all breaking changes.
+::
+
+The sections below highlight changes that are most relevant to Nuxt application developers and module authors.
+
+#### Package and Import Path Changes
+
+The `nitropack` package has been renamed to `nitro`. All import paths have changed:
+
+| Before | After |
+|---|---|
+| `nitropack` | `nitro` |
+| `nitropack/types` | `nitro/types` |
+| `nitropack/runtime` | `nitro/runtime` |
+| `h3` (for server utilities) | `nitro/h3` |
+
+Auto-imports within server routes (`defineEventHandler`, `getQuery`, `readBody`, `useRuntimeConfig`, etc.) continue to work without changes.
+
+If you have explicit imports in server code, update them:
+
+```diff
+- import { defineEventHandler, getQuery } from 'h3'
++ import { defineEventHandler, getQuery } from 'nitro/h3'
+```
+
+**For module authors**, type augmentations must target the new module path:
+
+```diff
+- declare module 'nitropack/types' {
++ declare module 'nitro/types' {
+    interface NitroRouteRules {
+      myModule?: { /* ... */ }
+    }
+  }
+```
+
+#### Error Handling: `status`/`statusText` replace `statusCode`/`statusMessage`
+
+h3 v2 renames the error properties to align with Web standards:
+
+```diff
+  createError({
+-   statusCode: 404,
+-   statusMessage: 'Not Found',
++   status: 404,
++   statusText: 'Not Found',
+  })
+```
+
+In server routes, the error class is now `HTTPError` (replacing `createError` from `h3`):
+
+```diff
+- import { createError } from 'h3'
++ import { HTTPError } from 'nitro/h3'
+
+  export default defineEventHandler(() => {
+-   throw createError({ statusCode: 400, statusMessage: 'Bad request' })
++   throw new HTTPError({ status: 400, statusText: 'Bad request' })
+  })
+```
+
+::note
+In the Vue part of your app (the `app/` directory), Nuxt's `createError` composable continues to work and is the recommended way to throw errors.
+::
+
+#### Server Event API Changes (h3 v2)
+
+The `H3Event` object now uses Web standard APIs:
+
+**Request properties:**
+```diff
+- event.path              // string
++ event.url.pathname      // URL object - use .pathname, .search, .hash
+
+- event.method            // string
++ event.req.method        // via Web Request object
+
+- event.node.req.headers  // Node.js IncomingHttpHeaders
++ event.req.headers       // Web Headers API (.get(), .set(), .has())
+```
+
+**Response properties:**
+```diff
+- event.node.res.statusCode = 200
++ event.res.status = 200
+
+- event.node.res.statusMessage = 'OK'
++ event.res.statusText = 'OK'
+
+- setResponseHeader(event, 'x-custom', 'value')
++ event.res.headers.set('x-custom', 'value')
+
+- appendResponseHeader(event, 'set-cookie', cookie)
++ event.res.headers.append('set-cookie', cookie)
+```
+
+#### `useRuntimeConfig()` No Longer Accepts `event`
+
+In Nitro v3, `useRuntimeConfig()` no longer requires (or accepts) an `event` argument in server routes:
+
+```diff
+  export default defineEventHandler((event) => {
+-   const config = useRuntimeConfig(event)
++   const config = useRuntimeConfig()
+  })
+```
+
+#### Route Rules: `statusCode` Renamed to `status`
+
+If you define redirect route rules, the property name has changed:
+
+```diff
+  export default defineNuxtConfig({
+    routeRules: {
+      '/old-page': {
+-       redirect: { to: '/new-page', statusCode: 302 },
++       redirect: { to: '/new-page', status: 302 },
+      },
+    },
+  })
+```
+
+#### For Module Authors: Additional Changes
+
+- **Nitro plugin imports**: Use `import { defineNitroPlugin } from 'nitro/runtime'` for explicit imports (auto-imports still work).
+- **Runtime hooks**: `nitroApp.hooks.hook('beforeResponse', ...)` and `nitroApp.hooks.hook('afterResponse', ...)` have been replaced by `nitroApp.hooks.hook('response', ...)`.
+- **`getRouteRules()` from `nitro/app`**: On the server, the Nitro helper changed from `getRouteRules(event)` to `getRouteRules(method, pathname)`, which returns `{ routeRules }`.
+
 ### Non-Async `callHook`
 
 🚦 **Impact Level**: Minimal

package/2.directory-structure/1.app/3.error.md

@@ -37,10 +37,6 @@ interface NuxtError {
   statusText?: string
   data?: unknown
   cause?: unknown
-  // legacy/deprecated equivalent of `status`
-  statusCode: number
-  // legacy/deprecated equivalent of `statusText`
-  statusMessage?: string
 }
 ```
 

package/2.directory-structure/1.modules.md

@@ -43,6 +43,8 @@ export default defineNuxtModule({
 ```
 
 ```ts twoslash [modules/hello/runtime/api-route.ts]
+import { defineEventHandler } from 'nitro/h3'
+
 export default defineEventHandler(() => {
   return { hello: 'world' }
 })

package/2.directory-structure/1.server.md

@@ -19,9 +19,11 @@ Nuxt automatically scans files inside these directories to register API and serv
 
 Each file should export a default function defined with `defineEventHandler()` or `eventHandler()` (alias).
 
-The handler can directly return JSON data, a `Promise`, or use `event.node.res.end()` to send a response.
+The handler can directly return JSON data, a `Promise`, or a `Response` object.
 
 ```ts twoslash [server/api/hello.ts]
+import { defineEventHandler } from 'nitro/h3'
+
 export default defineEventHandler((event) => {
   return {
     hello: 'world',
@@ -322,7 +324,7 @@ export default defineEventHandler((event) => {
 ::code-group
 ```ts [server/api/foo.ts]
 export default defineEventHandler(async (event) => {
-  const config = useRuntimeConfig(event)
+  const config = useRuntimeConfig()
 
   const repo = await $fetch('https://api.github.com/repos/nuxt/nuxt', {
     headers: {

package/3.guide/4.modules/4.recipes-advanced.md

@@ -144,7 +144,7 @@ export default defineNuxtModule({
         interface MyModuleNitroRules {
           myModule?: { foo: 'bar' }
         }
-        declare module 'nitropack/types' {
+        declare module 'nitro/types' {
           interface NitroRouteRules extends MyModuleNitroRules {}
           interface NitroRouteConfig extends MyModuleNitroRules {}
         }

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

@@ -136,7 +136,7 @@ You can access runtime config within the server routes as well using `useRuntime
 
 ```ts [server/api/test.ts]
 export default defineEventHandler(async (event) => {
-  const { apiSecret } = useRuntimeConfig(event)
+  const { apiSecret } = useRuntimeConfig()
   const result = await $fetch('https://my.api.com/test', {
     headers: {
       Authorization: `Bearer ${apiSecret}`,

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

@@ -90,7 +90,7 @@ declare module '#app' {
   }
 }
 
-declare module 'nitropack/types' {
+declare module 'nitro/types' {
   interface NitroRuntimeHooks {
     'your-nitro-hook': () => void
   }

package/4.api/2.composables/use-runtime-config.md

@@ -18,7 +18,7 @@ const config = useRuntimeConfig()
 
 ```ts [server/api/foo.ts]
 export default defineEventHandler((event) => {
-  const config = useRuntimeConfig(event)
+  const config = useRuntimeConfig()
 })
 ```
 
@@ -56,7 +56,7 @@ To access runtime config, we can use `useRuntimeConfig()` composable:
 
 ```ts [server/api/test.ts]
 export default defineEventHandler(async (event) => {
-  const config = useRuntimeConfig(event)
+  const config = useRuntimeConfig()
 
   // Access public variables
   const result = await $fetch(`/test`, {
@@ -132,7 +132,7 @@ And then access the new CDN url using `config.app.cdnURL`.
 
 ```ts [server/api/foo.ts]
 export default defineEventHandler((event) => {
-  const config = useRuntimeConfig(event)
+  const config = useRuntimeConfig()
 
   // Access cdnURL universally
   const cdnURL = config.app.cdnURL

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

@@ -73,6 +73,8 @@ export default defineNuxtModule({
 ```
 
 ```ts twoslash [runtime/robots.get.ts]
+import { defineEventHandler } from 'nitro/h3'
+
 export default defineEventHandler(() => {
   return {
     body: `User-agent: *\nDisallow: /`,
@@ -96,7 +98,7 @@ Adds a Nitro server handler to be used only in development mode. This handler wi
 ### Usage
 
 ```ts twoslash
-import { defineEventHandler } from 'h3'
+import { defineEventHandler } from 'nitro/h3'
 import { addDevServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({
@@ -117,7 +119,7 @@ export default defineNuxtModule({
 
 ```ts twoslash
 // @errors: 2391
-import type { NitroDevEventHandler } from 'nitropack/types'
+import type { NitroDevEventHandler } from 'nitro/types'
 // ---cut---
 function addDevServerHandler (handler: NitroDevEventHandler): void
 ```
@@ -198,7 +200,7 @@ You can read more about Nitro plugins in the [Nitro documentation](https://nitro
 ::
 
 ::warning
-It is necessary to explicitly import `defineNitroPlugin` from `nitropack/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.
+It is necessary to explicitly import `defineNitroPlugin` from `nitro/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.
 ::
 
 ### Usage
@@ -242,17 +244,15 @@ export default defineNuxtModule({
 ```
 
 ```ts [runtime/plugin.ts]
+import { defineNitroPlugin } from 'nitro/runtime'
+
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('request', (event) => {
-    console.log('on request', event.path)
-  })
-
-  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
-    console.log('on response', event.path, { body })
+    console.log('on request', event.req.url)
   })
 
-  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
-    console.log('on after response', event.path, { body })
+  nitroApp.hooks.hook('response', async (res) => {
+    console.log('on response', await res.text())
   })
 })
 ```
@@ -415,6 +415,8 @@ export function useApiSecret () {
 You can then use the `useApiSecret` function in your server code:
 
 ```ts twoslash [runtime/server/api/hello.ts]
+import { defineEventHandler } from 'nitro/h3'
+
 const useApiSecret = (): string => ''
 // ---cut---
 export default defineEventHandler(() => {
@@ -493,6 +495,8 @@ export function hello () {
 You can then use the `hello` function in your server code.
 
 ```ts twoslash [runtime/server/api/hello.ts]
+import { defineEventHandler } from 'nitro/h3'
+
 function hello () {
   return 'Hello from server utils!'
 }

package/4.api/5.kit/7.pages.md

@@ -88,7 +88,7 @@ export default defineNuxtModule({
     extendRouteRules('/preview', {
       redirect: {
         to: '/preview-new',
-        statusCode: 302,
+        status: 302,
       },
     })
 

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

@@ -1494,9 +1494,9 @@ Modules to generate deep aliases for within `compilerOptions.paths`. This does n
 - **Default**
 ```json
 [
-  "nitropack/types",
-  "nitropack/runtime",
-  "nitropack",
+  "nitro/types",
+  "nitro/runtime",
+  "nitro",
   "defu",
   "h3",
   "consola",

package/7.migration/8.runtime-config.md

@@ -42,7 +42,7 @@ console.log(config.public.apiBase)
 
 ```ts [server/api/hello.ts]
 export default defineEventhandler((event) => {
-  const config = useRuntimeConfig(event)
+  const config = useRuntimeConfig()
   // In server, you can now access config.apiSecret, in addition to config.public
   console.log(config.apiSecret)
   console.log(config.public.apiBase)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29554472.d5d8ce2f",
+  "version": "5.0.0-29554612.0e08003b",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",