@nuxt/docs-nightly 4.6.0-29803612.ea5d49fb → 4.6.0-29809894.6056487a

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

@@ -551,6 +551,80 @@ export default defineNuxtConfig({
 })
 ```
 
+### Typed `$fetch` Rebuilt on Generated Route Types
+
+🚦 **Impact Level**: Medium
+
+#### What Changed
+
+With `compatibilityVersion: 5`, `$fetch` and `useFetch` are typed from the routes Nuxt's server
+builder reports, rather than from nitro's `InternalApi` interface. As well as response types, a
+`body`, `query` or `headers` the matching handler validates are now enforced on the call, a method
+the route does not handle is rejected, and a response is typed as it arrives over the wire, so a
+`Date` a handler returns is a `string` at the call site.
+
+Two things follow from this:
+
+- Routes you augmented by hand on nitro's `InternalApi` are no longer picked up. Augment
+  `ServerRoutes` from `@nuxt/schema` instead.
+- The `params` option is no longer accepted by `$fetch` or `useFetch`. It was an alias for `query`.
+
+#### Reasons for Change
+
+Nitro v3 drops typed fetch, and the old implementation did not scale past about 300 routes. The new
+generated route types cost the same to check whatever the route count, and carry enough information
+to type the request as well as the response. `params` is dropped so the name is free for named route
+parameters later.
+
+#### Migration Steps
+
+Move any `params` option to `query`:
+
+```diff
+  const { data } = await useFetch('/api/search', {
+-   params: { q: 'nuxt' },
++   query: { q: 'nuxt' },
+  })
+```
+
+Move any manual route augmentation from `InternalApi` to `ServerRoutes`:
+
+```diff [shared/server-routes.d.ts]
+- declare module 'nitropack' {
+-   interface InternalApi {
+-     '/api/hello': { get: { message: string } }
+-   }
+- }
++ import type { Endpoint } from 'nuxt/app'
++
++ declare module '@nuxt/schema' {
++   interface ServerRoutes {
++     '/api/hello': {
++       [Endpoint]: {
++         GET: { response: { message: string } }
++       }
++     }
++   }
++ }
+```
+
+::note
+While Nuxt 4 runs on nitro v2, nitro declares a global `$fetch` of its own, typed from
+`InternalApi`. Import `$fetch` from `#build/fetch` where you want the generated route types to apply
+to a direct call; `useFetch`, `useLazyFetch` and `useRequestFetch()` are unaffected.
+::
+
+::tip
+Either typing can be selected on its own with
+[`experimental.routeTypedFetch`](/docs/4.x/guide/going-further/experimental-features#routetypedfetch),
+so you can adopt this before moving to Nuxt 5, or move to Nuxt 5 with `routeTypedFetch: false` and
+adopt it separately. The option is temporary: from Nuxt 5 the generated route set is the only
+source.
+::
+
+Set [`experimental.strictRouteTypes`](/docs/4.x/guide/going-further/experimental-features#strictroutetypes)
+to reject a path no route answers.
+
 ### TypeScript `baseUrl` Is Ignored
 
 🚦 **Impact Level**: Minimal

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

@@ -1050,6 +1050,101 @@ export default defineNuxtConfig({
 })
 ```
 
+## routeTypedFetch
+
+Type `$fetch` and `useFetch` from the routes your server builder reports, rather than from the
+responses nitro contributes to `ServerRoutes` through its `InternalApi` interface.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    routeTypedFetch: true,
+  },
+})
+```
+
+The generated route set carries the `body`, `query` and `headers` a handler validates as well as its
+response, typed as it arrives over the wire, so a resolving call is typed more tightly than before:
+
+- a `Date` a handler returns is a `string` at the call site
+- a `body` the handler validates cannot be omitted or given the wrong shape
+- a method the route does not answer is rejected
+- `params` is no longer accepted, since it was only ever an alias for `query`
+- a route you registered by augmenting `ServerRoutes` by hand needs rewriting, as the two
+  descriptions of a route differ (see [the upgrade guide](/docs/4.x/getting-started/upgrade#typed-fetch-rebuilt-on-generated-route-types))
+
+Because of those, it is opt-in, and `future.compatibilityVersion: 5` enables it. Setting it
+explicitly selects either typing whatever the compatibility version, so you can adopt it before
+moving to Nuxt 5, or move to Nuxt 5 with `routeTypedFetch: false` and adopt it separately.
+
+::note
+This option exists only while both typings are supported. From Nuxt 5 the generated route set is the
+only source and the option is gone.
+::
+
+::note
+While Nuxt 4 runs on nitro v2, nitro declares a global `$fetch` of its own, typed from
+`InternalApi`. Import `$fetch` from `#build/fetch` where you want the generated route types to apply
+to a direct call; `useFetch`, `useLazyFetch` and `useRequestFetch()` are unaffected.
+::
+
+## strictRouteTypes
+
+Reject a request to a path no server route answers. Requires
+[`routeTypedFetch`](#routetypedfetch), which types `$fetch` and `useFetch` from the routes your
+server will serve.
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    routeTypedFetch: true,
+    strictRouteTypes: true,
+  },
+})
+```
+
+With `routeTypedFetch` enabled a response is typed by the handler that answers it whatever this
+option is set to. What the option decides is whether a path Nuxt does not recognise is an error or
+is simply typed as `unknown`.
+
+- `false` (default) - a path Nuxt does not recognise is accepted and resolves to `unknown`, and no
+  method is rejected. Nuxt cannot see every way a request may be answered: nitro middleware, a
+  [`routeRules`](/docs/4.x/guide/concepts/rendering#hybrid-rendering) proxy or a catch-all handler
+  can answer a path no route describes.
+- `true` - only the routes your server builder reports are accepted, for the methods they answer.
+- `'isomorphic'` - as `true`, and your pages are included as `GET` routes returning `string`, so
+  `$fetch('/about')` is typed by the route the Vue router serves rather than rejected.
+
+With the option on, a typo and a method the route does not answer are both errors:
+
+```ts
+// server/api/todos.post.ts answers POST only
+await $fetch('/api/todos', { method: 'POST' })
+await $fetch('/api/todo', { method: 'POST' })
+//           ^ no POST route matches '/api/todo'
+await $fetch('/api/todos')
+//           ^ no GET route matches '/api/todos'
+```
+
+Two things stay accepted, because they are not Nuxt's to describe: an absolute URL
+(`$fetch('https://example.com')`), and a path built at runtime, which resolves to `unknown` as it
+does with the option off. A `baseURL` is resolved into the path before it is matched, so a request
+made through one is checked against the route it actually asks for. Naming the response type also
+opts a call out, since doing so turns off inference for the request:
+
+```ts
+const data = await $fetch<{ id: string }>(`/api/${resource}`)
+```
+
+::note
+Files in your `public/` directory are not routes your server builder reports, so requesting one
+with `strictRouteTypes` enabled is an error. Fetch those with an explicit response type, or leave
+the option off.
+::
+
+Set this only where your routing is enumerable. An app with a catch-all page under `'isomorphic'`
+matches every path, which is correct but means the option constrains nothing.
+
 ## pendingWhenIdle
 
 `pendingWhenIdle` controls the `pending` ref returned by `useAsyncData` and `useFetch`.

package/4.api/6.advanced/1.hooks.md

@@ -57,6 +57,7 @@ Check the [schema source code](https://github.com/nuxt/nuxt/blob/main/packages/s
 | `pages:extend`              | `pages`                                                  | Called after page routes are scanned from the file system.                                                                                                                                                                                                                                   |
 | `pages:resolved`            | `pages`                                                  | Called after page routes have been augmented with scanned metadata.                                                                                                                                                                                                                          |
 | `pages:routerOptions`       | `{ files: Array<{ path: string, optional?: boolean }> }` | Called when resolving `router.options` files. Later items in the array override earlier ones.                                                                                                                                                                                                |
+| `server:routes`             | `routes`, `context`                                      | Called when Nuxt needs the full set of route handlers the server will serve, so that it can type `$fetch` and `useFetch` against them.                                                                                                                                                        |
 | `server:devHandler`         | `handler`                                                | Called when the dev middleware is being registered on the Nitro dev server.                                                                                                                                                                                                                  |
 | `imports:sources`           | `presets`                                                | Called at setup allowing modules to extend sources.                                                                                                                                                                                                                                          |
 | `imports:extend`            | `imports`                                                | Called at setup allowing modules to extend imports.                                                                                                                                                                                                                                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.6.0-29803612.ea5d49fb",
+  "version": "4.6.0-29809894.6056487a",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",