@nuxt/docs-nightly 5.0.0-2610271652-3b4f925 → 5.0.0-2610272000-c73c4e1

package/3.guide/1.concepts/6.server-components.md

@@ -91,7 +91,7 @@ Because props come from the request (URL query or body), treat them as untrusted
 
 Treating props as untrusted includes their size: validate or clamp numeric and array props before using them to drive a `v-for` or other work that grows with their value. Nuxt caps numeric `v-for` sources at 10,000 iterations in island renders, but only as a safety net, not as validation.
 
-Props a component does not declare fall through as attributes onto its single root element, so an island whose root is a polymorphic component (e.g. from `reka-ui` / `@nuxt/ui`) can receive attributes you did not bind. Set `defineOptions({ inheritAttrs: false })`{lang=ts} on such islands, or declare the props you accept.
+Props a component does not declare fall through as attributes onto its single root element, so an island whose root is a polymorphic component (e.g. from `reka-ui` / `@nuxt/ui`) can receive attributes you did not bind. Set `defineOptions({ inheritAttrs: false })`{lang=ts} on such islands, or declare the props you accept. As with any Vue component, fall-through attributes include event handler attributes such as `onclick` or `onfocus`, which the browser runs as JavaScript, so don't spread an object you don't control (such as `route.query`) onto a server component or into the `props` of `<NuxtIsland>`{lang=vue}.
 
 To switch components based on caller input, map a discriminator through an allowlist of imported components rather than passing the raw prop:
 

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

@@ -287,6 +287,30 @@ This is opt-in because it can break apps that rely on runtime routing:
 The option is disabled automatically in development, when `hashMode` is enabled, when a root-level catch-all page (such as `pages/[...slug].vue`) matches every path, and when a custom `app/router.options` file may modify `routes` (a file whose default export is a plain object without a `routes` key remains compatible).
 ::
 
+## templateDiagnostics
+
+Warns at build time about template mistakes the Vue compiler cannot detect, because they depend on what Nuxt knows about your app:
+
+- [`NUXT_B4025`](/docs/errors/b4025): a `<NuxtLink>` whose static `to` matches no page route
+- [`NUXT_B3014`](/docs/errors/b3014): `v-on` or `v-model` on a server component
+- [`NUXT_B3015`](/docs/errors/b3015): a function or class instance passed as a prop to a server component, or in the `props` of a `<NuxtIsland>`
+
+Warnings are printed to the terminal with the template location and, in development, sent to open error pages and overlays.
+
+This flag is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    templateDiagnostics: false,
+  },
+})
+```
+
+::warning
+The route check cannot see routes added at runtime with `router.addRoute()` or paths that route middleware redirects, and is skipped when a custom `app/router.options` file may modify `routes`.
+::
+
 ## clientFallback
 
 Enables the experimental [`<NuxtClientFallback>`](/docs/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.

package/4.api/3.utils/on-nuxt-ready.md

@@ -24,3 +24,58 @@ export default defineNuxtPlugin(() => {
 ```
 
 It is 'safe' to run even after your app has initialized. In this case, then the code will be registered to run in the next idle callback.
+
+## Type
+
+```ts [Signature]
+export function onNuxtReady (callback: () => any, options?: OnNuxtReadyOptions): void
+
+interface OnNuxtReadyOptions {
+  timeout?: number
+  signal?: AbortSignal
+}
+```
+
+### `callback`
+
+**Type**: `() => any`
+
+The function to run once your app has finished initializing and the browser is idle.
+
+### `options` (optional)
+
+**Type**: `OnNuxtReadyOptions`
+
+- `timeout` (optional)
+
+  **Type**: `number`
+
+  The maximum number of milliseconds to wait for the browser to become idle once your app is ready. It is passed to [`requestIdleCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback#timeout). Without it, the callback may be delayed for several seconds if the browser does not schedule an idle period, which can happen in headless browsers.
+
+```ts [app/plugins/ready.client.ts]
+export default defineNuxtPlugin(() => {
+  onNuxtReady(() => {
+    // runs when the browser is idle, or about 2 seconds after your app is ready, whichever comes first
+  }, { timeout: 2000 })
+})
+```
+
+- `signal` (optional)
+
+  **Type**: `AbortSignal`
+
+  Skips the callback if the signal is aborted before it runs. This is useful when calling `onNuxtReady` from a component that may unmount before your app is ready.
+
+```vue [app/components/MyComponent.vue]
+<script setup lang="ts">
+const controller = new AbortController()
+
+onMounted(() => {
+  onNuxtReady(() => {
+    // does not run if the component unmounts first
+  }, { signal: controller.signal })
+})
+
+onBeforeUnmount(() => controller.abort())
+</script>
+```

package/errors/b3014.md

@@ -0,0 +1,27 @@
+---
+title: 'NUXT_B3014'
+description: 'Event listener on a server component'
+navigation: false
+---
+
+# B3014
+
+A template uses `v-on` (or `@`) or `v-model` on a server component. Server components render on the server only and ship no JavaScript for themselves, so they never emit events and cannot update a `v-model` binding. The listener is never called.
+
+This warning is reported unless [`experimental.templateDiagnostics`](/docs/guide/going-further/experimental-features#templatediagnostics) is disabled. `@error` is not reported: a server component emits `error` when it fails to load.
+
+## Resolution
+
+Render the interactive part on the client. You can pair the server component with a `.client.vue` component of the same name, render an interactive child with the `nuxt-client` attribute (with `experimental.componentIslands.selectiveClient` enabled), or move the listener to a client component that wraps the server component.
+
+```vue [app/components/Counter.server.vue]
+<template>
+  <div>
+    <!-- rendered on the server, then hydrated on the client -->
+    <CounterButton nuxt-client />
+  </div>
+</template>
+```
+
+::read-more{to="/docs/guide/concepts/server-components"}
+::

package/errors/b3015.md

@@ -0,0 +1,27 @@
+---
+title: 'NUXT_B3015'
+description: 'Non-serializable prop on a server component'
+navigation: false
+---
+
+# B3015
+
+A template passes a function, a class or a class instance (such as `new Date()`) as a prop to a server component, or in the `props` or `context` of a `<NuxtIsland>`. Props of a server component are serialized as JSON and sent to the server to render it, so these values cannot reach the component intact.
+
+This warning is reported unless [`experimental.templateDiagnostics`](/docs/guide/going-further/experimental-features#templatediagnostics) is disabled. Only values that can be seen in the template are checked: inline functions, `new` expressions, and functions or classes declared at the top level of `<script setup>`.
+
+## Resolution
+
+Pass only JSON-serializable values (strings, numbers, booleans, `null`, arrays and plain objects), and move the logic that needs the function into the server component:
+
+```diff [app/pages/index.vue]
+ <template>
+-  <PriceTag :format="value => `$${value}`" :value="price" />
++  <PriceTag currency="USD" :value="price" />
+ </template>
+```
+
+If the component needs a function from its parent, render it on the client instead of as a server component.
+
+::read-more{to="/docs/guide/concepts/server-components"}
+::

package/errors/b4025.md

@@ -0,0 +1,31 @@
+---
+title: 'NUXT_B4025'
+description: 'NuxtLink to an unknown route'
+navigation: false
+---
+
+# B4025
+
+A template contains a `<NuxtLink>` with a static `to` (or `href`) that does not match any page route, so following the link would show a 404 page.
+
+This warning is reported unless [`experimental.templateDiagnostics`](/docs/guide/going-further/experimental-features#templatediagnostics) is disabled. Only static, absolute paths are checked: links with a bound `:to`, external URLs, relative paths, hash-only and query-only links, and links with the `external` prop are not. Dynamic route segments and catch-all routes match any value, and paths that a route rule redirects are accepted.
+
+A path that only matches as the prefix of a route is reported: with only `app/pages/users/[id].vue`, a link to `/users` has no page to render.
+
+## Resolution
+
+Check the path for typos, or add the page it should link to. If the link points at something other than a page (a server route, a file in `public/`, or another app on the same domain), set the `external` prop so that it is followed by the browser rather than the Vue router:
+
+```vue
+<template>
+  <NuxtLink
+    to="/api/export.csv"
+    external
+  >
+    Download
+  </NuxtLink>
+</template>
+```
+
+::read-more{to="/docs/api/components/nuxt-link"}
+::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-2610271652-3b4f925",
+  "version": "5.0.0-2610272000-c73c4e1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",