@nuxt/docs-nightly 4.6.0-29838870.2da76d24 → 4.6.0-29840230.9d862ea9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -77,6 +77,58 @@ This list describes what the flag changes on Nuxt 4. Nuxt 5 itself carries furth
|
|
|
77
77
|
|
|
78
78
|
The migration steps for each change, and everything else the upgrade brings, are documented in the [Nuxt 5 upgrade guide](https://nuxt.com/docs/5.x/getting-started/upgrade).
|
|
79
79
|
|
|
80
|
+
## Moving to `nuxt/server`
|
|
81
|
+
|
|
82
|
+
From Nuxt 4.6, server code can import its handler and helpers from [`nuxt/server`](/docs/guide/going-further/server-imports) rather than from h3, so the same file runs on Nuxt 4 (`nitropack` v2 and h3 v1) and on [Nuxt 5](https://nuxt.com/docs/5.x/getting-started/upgrade) (Nitro v3 and h3 v2).
|
|
83
|
+
|
|
84
|
+
On Nuxt 4.6, import `defineEventHandler` and the helpers from `nuxt/server` explicitly. The auto-imported names of the same spelling are h3 v1's, and h3's `defineEventHandler` passes your handler a different event from the one the `nuxt/server` helpers read.
|
|
85
|
+
|
|
86
|
+
```diff [server/api/hello.ts]
|
|
87
|
+
+ import { defineEventHandler, getQuery } from 'nuxt/server'
|
|
88
|
+
+
|
|
89
|
+
export default defineEventHandler((event) => {
|
|
90
|
+
const { name } = getQuery<{ name?: string }>(event)
|
|
91
|
+
return { message: `Hello, ${name ?? 'world'}!` }
|
|
92
|
+
})
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
On Nuxt 5 the same names are auto-imported from `nuxt/server`, so explicit imports written on Nuxt 4.6 keep working unchanged.
|
|
96
|
+
|
|
97
|
+
### Differences From h3 v1
|
|
98
|
+
|
|
99
|
+
| h3 v1 | `nuxt/server` |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `sendRedirect(event, location)` sends the response. | `sendRedirect(event, location)` returns the response body: `return sendRedirect(event, '/login')`. |
|
|
102
|
+
| `getRouterParams(event)` returns decoded values. | `getRouterParams(event)` returns the values as they appear in the URL. Pass `{ decode: true }` to decode them. |
|
|
103
|
+
| `handleCors(event, options)` returns `true` when it answered a preflight request. | `handleCors(event, options)` returns the preflight `Response` to return from the handler, or `false`. |
|
|
104
|
+
| `readValidatedBody` and `getValidatedQuery` take a validation function. | They take a [Standard Schema](https://standardschema.dev) or a function. |
|
|
105
|
+
| `createError({ statusCode, statusMessage })` | `createError({ status, statusText })` |
|
|
106
|
+
| `useSession` and friends seal an `h3` cookie with the `password` you pass. | They seal a `nuxt-session` cookie, by default with a secret derived from `appSecret`. The two are not interchangeable: a session one issues does not unseal with the other. |
|
|
107
|
+
| `getResponseHeader`, `setResponseHeader`, `appendResponseHeader`, `removeResponseHeader` | `event.res.headers.get()`, `.set()`, `.append()`, `.delete()` |
|
|
108
|
+
| `getMethod(event)`, `getRequestHost(event)` | `event.req.method`, `event.url.host` |
|
|
109
|
+
|
|
110
|
+
### Helpers Outside `nuxt/server`
|
|
111
|
+
|
|
112
|
+
For h3 or Nitro helpers that `nuxt/server` does not provide, such as `readMultipartFormData`, `proxyRequest`, `useStorage` or `defineCachedEventHandler`, pass them `toNuxtRequestEvent(event)`, which is the h3 v1 event on Nuxt 4. Code that does this is tied to the server runtime and needs revisiting on Nuxt 5.
|
|
113
|
+
|
|
114
|
+
```ts [server/api/upload.post.ts]
|
|
115
|
+
import { defineEventHandler, toNuxtRequestEvent } from 'nuxt/server'
|
|
116
|
+
import { readMultipartFormData } from 'h3'
|
|
117
|
+
|
|
118
|
+
export default defineEventHandler(async (event) => {
|
|
119
|
+
const parts = await readMultipartFormData(toNuxtRequestEvent(event))
|
|
120
|
+
return { received: parts?.length ?? 0 }
|
|
121
|
+
})
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### `NUXT_E8012`
|
|
125
|
+
|
|
126
|
+
A request fails with a `500` whose message starts with `[NUXT_E8012]` when a `nuxt/server` helper such as `readValidatedBody`, `getValidatedQuery`, `handleCors` or `useSession` receives an h3 event. This means the handler was defined with h3's `defineEventHandler` (usually the auto-imported one). Import `defineEventHandler` from `nuxt/server` in the same file as the helpers.
|
|
127
|
+
|
|
128
|
+
### Application Secret
|
|
129
|
+
|
|
130
|
+
The `nuxt/server` session helpers and `deriveSecret` read `runtimeConfig.appSecret`, which you set with `NUXT_APP_SECRET`. On Nuxt 4, `nitropack` v2 parses environment overrides, so a secret made only of digits arrives as a number; see [the application secret](/docs/guide/going-further/runtime-config#application-secret) for how to avoid this.
|
|
131
|
+
|
|
80
132
|
## Migrating to Nuxt 4
|
|
81
133
|
|
|
82
134
|
Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.
|
|
@@ -55,6 +55,10 @@ Types are exported alongside the utilities: `RequestEvent`, `RequestEventContext
|
|
|
55
55
|
|
|
56
56
|
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.
|
|
57
57
|
|
|
58
|
+
::read-more{to="/docs/getting-started/upgrade#moving-to-nuxtserver"}
|
|
59
|
+
Moving existing server code to `nuxt/server`, and how its helpers differ from h3's.
|
|
60
|
+
::
|
|
61
|
+
|
|
58
62
|
::tip
|
|
59
63
|
`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.
|
|
60
64
|
::
|