@nuxt/docs-nightly 4.6.0-29803612.ea5d49fb → 4.6.0-29809999.0506e6c6

package/1.getting-started/17.testing.md

@@ -265,16 +265,15 @@ Under the hood, `mountSuspended` wraps `mount` from `@vue/test-utils`, so you ca
 
 For example:
 
-```ts twoslash
+```ts twoslash [tests/components/SomeComponents.nuxt.spec.ts]
 // @noErrors
-import { expect, it } from 'vitest'
 import type { Component } from 'vue'
 
 declare module '#components' {
   export const SomeComponent: Component
 }
 // ---cut---
-// tests/components/SomeComponents.nuxt.spec.ts
+import { expect, it } from 'vitest'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import { SomeComponent } from '#components'
 
@@ -286,15 +285,11 @@ it('can mount some component', async () => {
 })
 ```
 
-```ts twoslash
-// @noErrors
+```ts twoslash [tests/App.nuxt.spec.ts]
 import { expect, it } from 'vitest'
-// ---cut---
-// tests/components/SomeComponents.nuxt.spec.ts
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import App from '~/app.vue'
 
-// tests/App.nuxt.spec.ts
 it('can also mount an app', async () => {
   const component = await mountSuspended(App, { route: '/test' })
   expect(component.html()).toMatchInlineSnapshot(`
@@ -306,9 +301,34 @@ it('can also mount an app', async () => {
 })
 ```
 
+If you need to spy on component setup state, you can set the `spy` option to `true` and access the return value of the setup via `setupState`.
+
+```ts twoslash [tests/components/SomeComponents.nuxt.spec.ts]
+// @noErrors
+import type { Component } from 'vue'
+
+declare module '#components' {
+  export const SomeComponent: Component
+}
+// ---cut---
+import { expect, it, vi } from 'vitest'
+import { mountSuspended } from '@nuxt/test-utils/runtime'
+import { SomeComponent } from '#components'
+
+it('can spy on setup state', async () => {
+  const component = await mountSuspended(SomeComponent, { spy: true })
+  vi.mocked(component.setupState.someMethod).mockImplementation(() => 'mocked')
+})
+```
+
 The options object accepts `@vue/test-utils` mount options and the following properties:
 
   - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+  - `spy`: enable spy component setup state (default `false`).
+
+The return object includes the `@vue/test-utils` mount result and the following properties:
+
+  - `setupState`: the return value of the component setup.
 
 #### `renderSuspended`
 
@@ -322,16 +342,15 @@ The passed in component will be rendered inside a `<div id="test-wrapper"></div>
 
 Examples:
 
-```ts twoslash
+```ts twoslash [tests/components/SomeComponents.nuxt.spec.ts]
 // @noErrors
-import { expect, it } from 'vitest'
 import type { Component } from 'vue'
 
 declare module '#components' {
   export const SomeComponent: Component
 }
 // ---cut---
-// tests/components/SomeComponents.nuxt.spec.ts
+import { expect, it } from 'vitest'
 import { renderSuspended } from '@nuxt/test-utils/runtime'
 import { SomeComponent } from '#components'
 import { screen } from '@testing-library/vue'
@@ -342,11 +361,8 @@ it('can render some component', async () => {
 })
 ```
 
-```ts twoslash
-// @noErrors
+```ts twoslash [tests/App.nuxt.spec.ts]
 import { expect, it } from 'vitest'
-// ---cut---
-// tests/App.nuxt.spec.ts
 import { renderSuspended } from '@nuxt/test-utils/runtime'
 import App from '~/app.vue'
 
@@ -365,6 +381,11 @@ it('can also render an app', async () => {
 The options object accepts `@testing-library/vue` render options and the following properties:
 
   - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+  - `spy`: enable spy component setup state (default `false`). See the [`mountSuspended`](#mountsuspended) example above.
+
+The return object includes the `@testing-library/vue` render result and the following properties:
+
+  - `setupState`: the return value of the component setup.
 
 #### `mockNuxtImport`
 
@@ -658,6 +679,132 @@ If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and
 
 Congratulations, you're all set to start unit testing with `@vue/test-utils` in Nuxt! Happy testing!
 
+### Vitest Browser Mode
+
+`@nuxt/test-utils` provides helpers for testing in [Vitest Browser Mode](https://vitest.dev/guide/browser/) via `@nuxt/test-utils/browser`.
+
+#### Setup
+
+1. Install Vitest browser packages and a browser provider:
+
+   ::code-group{sync="pm"}
+   ```bash [npm]
+   npm i --save-dev @vitest/browser-playwright
+   ```
+   ```bash [yarn]
+   yarn add --dev @vitest/browser-playwright
+   ```
+   ```bash [pnpm]
+   pnpm add -D @vitest/browser-playwright
+   ```
+   ```bash [bun]
+   bun add --dev @vitest/browser-playwright
+   ```
+   ::
+
+2. Configure browser mode in your `vitest.config.ts`:
+
+   ```ts twoslash
+   // @errors: 2307
+   // ---cut---
+   import { defineConfig } from 'vitest/config'
+   import { defineVitestProject } from '@nuxt/test-utils/config'
+   import { playwright } from '@vitest/browser-playwright'
+
+   export default defineConfig({
+     test: {
+       projects: [
+         await defineVitestProject({
+           test: {
+             name: 'browser',
+             include: ['test/browser/**/*.{test,spec}.ts'],
+             browser: {
+               enabled: true,
+               provider: playwright(),
+               instances: [{ browser: 'chromium' }],
+             },
+             // If you want to enable `page.render` and automatic cleanup, add this setup file
+             setupFiles: ['@nuxt/test-utils/browser'],
+           },
+         }),
+       ],
+     },
+   })
+   ```
+
+   ::note
+   When adding `@nuxt/test-utils/browser` to `setupFiles`, if TypeScript does not automatically recognize the types for `page.render`, you can add `@nuxt/test-utils/browser` via `typescript.tsConfig.compilerOptions.types` in your `nuxt.config.ts`.
+   ::
+
+   ::note
+   If your Vitest browser mode tests live outside `test/nuxt/` (such as in `test/browser/`), see [Adding other test directories](#adding-other-test-directories) to add them to the TypeScript context.
+   ::
+
+#### Usage
+
+You can use `page.render` from `vitest/browser`:
+
+```ts twoslash [test/browser/components/MyCounter.nuxt.spec.ts]
+// @noErrors
+import type { Component } from 'vue'
+
+declare module '#components' {
+  export const MyCounter: Component
+}
+// ---cut---
+import { expect, it } from 'vitest'
+import { page } from 'vitest/browser'
+// If you added the setup file, the following import is not needed
+import '@nuxt/test-utils/browser'
+
+import { MyCounter } from '#components'
+
+it('counter button increments the count', async () => {
+  const screen = await page.render(MyCounter)
+  await screen.getByRole('button', { name: 'Increment' }).click()
+  await expect.element(screen.getByText('Count: 1')).toBeVisible()
+})
+```
+
+You can also import `render` directly from `@nuxt/test-utils/browser`:
+
+```ts twoslash
+// @noErrors
+import type { Component } from 'vue'
+
+declare module '#components' {
+  export const MyCounter: Component
+}
+// ---cut---
+import { expect, it } from 'vitest'
+import { render } from '@nuxt/test-utils/browser'
+import { MyCounter } from '#components'
+
+it('can render using the render helper', async () => {
+  const screen = await render(MyCounter)
+  await screen.getByRole('button', { name: 'Increment' }).click()
+  await expect.element(screen.getByText('Count: 1')).toBeVisible()
+})
+```
+
+The options object accepts `@vue/test-utils` mount options (use `container` instead of `attachTo`) and the following properties:
+
+  - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+  - `spy`: enable spy component setup state (default `false`). See the [`mountSuspended`](#mountsuspended) example above.
+  - `container`: custom `HTMLElement` container to render into (use this option instead of `@vue/test-utils` `attachTo`).
+  - `baseElement`: custom base `HTMLElement` (default `document.body`).
+
+The return object includes the following properties:
+
+  - `container`: the container `HTMLElement` the component is rendered into.
+  - `baseElement`: the base `HTMLElement` (default `document.body`).
+  - `locator`: root element `Locator`.
+  - `setupState`: the return value of the component setup, mocked when the `spy` option is enabled.
+  - `debug()`: print formatted DOM to console.
+  - `unmount()`: unmount the component. Also records a `nuxt.unmount` trace mark.
+  - `emitted()`: get emitted events.
+  - `rerender(props)`: re-render the component with new props. Also records a `nuxt.rerender` trace mark.
+
 ## End-To-End Testing
 
 For end-to-end testing, we support [Vitest](https://github.com/vitest-dev/vitest), [Jest](https://jestjs.io), [Cucumber](https://cucumber.io/) and [Playwright](https://playwright.dev/) as test runners.

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/2.directory-structure/1.app/3.app-config.md

@@ -67,7 +67,7 @@ Read more about the `updateAppConfig` utility.
 
 Nuxt tries to automatically generate a TypeScript interface from provided app config so you won't have to type it yourself.
 
-The fully inferred type is only available in app code (components, composables, plugins and so on). In server routes, code in the `shared/` directory and `nuxt.config`, keys defined in `app.config` files are typed as `unknown` instead: typing them there would require typechecking your app code outside the app context, where app auto-imports are not available. Keys defined inline in the `appConfig` option of `nuxt.config` are typed everywhere. If you need other keys typed outside app code, you can extend the `AppConfig` interface as described below. The location of the augmentation file determines which contexts see it: a `.d.ts` file in the `shared/` directory covers app code, shared code and server routes.
+The fully inferred type is only available in app code (components, composables, plugins and so on). In server routes, code in the `shared/` directory and `nuxt.config`, keys defined in `app.config` files are typed as `unknown` instead: typing them there would require typechecking your app code outside the app context, where app auto-imports are not available. Keys defined inline in the `appConfig` option of `nuxt.config` are typed everywhere. If you need other keys typed outside app code, you can extend the `SharedAppConfig` interface as described below. The location of the augmentation file determines which contexts see it: a `.d.ts` file in the `shared/` directory covers app code, shared code and server routes.
 
 However, there are some cases where you might want to type it yourself. There are two possible things you might want to type.
 
@@ -92,7 +92,7 @@ export {}
 
 ### App Config Output
 
-If you want to type the result of calling [`useAppConfig()`](/docs/4.x/api/composables/use-app-config), then you will want to extend `AppConfig`.
+If you want to type the result of calling [`useAppConfig()`](/docs/4.x/api/composables/use-app-config) in app code, then you will want to extend `AppConfig`. Outside app code (server routes, the `shared/` directory and `nuxt.config`) `useAppConfig()` returns `SharedAppConfig`, so extend that interface instead.
 
 ::warning
 Be careful when typing `AppConfig` as you will overwrite the types Nuxt infers from your actually defined app config.

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/3.guide/6.going-further/8.builders.md

@@ -211,6 +211,30 @@ 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`.
 
+## 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/4.x/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/4.x/guide/going-further/internals"}
 Learn more about the Nuxt interface and the build vs. runtime split.
 ::

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-29809999.0506e6c6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",