npm - @nuxt/docs-nightly - Versions diffs - 5.0.0-29662437.89c933ea → 5.0.0-29664396.5668d45c - Mend

@nuxt/docs-nightly 5.0.0-29662437.89c933ea → 5.0.0-29664396.5668d45c

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.

Files changed (2) hide show

package/3.guide/6.going-further/1.experimental-features.md +128 -0
package/package.json +1 -1

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

@@ -993,3 +993,131 @@ To use this feature, you need to:
 ::read-more{icon="i-simple-icons-github" to="https://github.com/KazariEX/dxup" target="_blank"}
 Learn more about **@dxup/nuxt**.
 ::
+## ssrStreaming
+Enables SSR streaming to dramatically improve Time to First Byte (TTFB). When enabled, the server sends the HTML shell (including `<head>`, styles, preload hints, and entry scripts) immediately, then streams the rendered body content progressively using Vue's `renderToWebStream`.
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    ssrStreaming: true,
+  },
+})
+```
+Streaming is automatically disabled for bot and crawler user agents (such as Googlebot, Bingbot, etc.) to ensure search engines receive fully-rendered HTML for SEO safety. The default pattern matches indexing crawlers only; Lighthouse and other audit tools deliberately fall outside it so synthetic measurements reflect the same streamed response real users get. You can customize the bot detection regex:
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    ssrStreaming: {
+      botRegex: /googlebot|bingbot|my-internal-crawler/i,
+    },
+  },
+})
+```
+You can also control streaming per-route using `routeRules`:
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    ssrStreaming: true,
+  },
+  routeRules: {
+    '/no-stream/**': { streaming: false },
+  },
+})
+```
+::warning
+**Automatic fallback to non-streamed rendering.** Streaming commits the response status and headers as soon as the shell is flushed, which is incompatible with features that need to mutate the response after render. Requests matching any of the following are not streamed; they use the buffered renderer, or short-circuit to a redirect or error response:
+- `routeRules` setting `noScripts`, `cache`, `isr`, `swr`, `redirect`, or `streaming: false` for the route
+- `ssr: false` routes (already SPA-rendered)
+- Bot/crawler user agents (controlled via `botRegex`)
+- Prerendered routes (`nuxi generate`)
+- Server-side `navigateTo()` redirects from plugins, middleware, or page setup
+- Fatal errors thrown during initial render (before the shell flushes)
+::
+::warning
+**Response status and headers must be set before the shell is flushed.** Streaming commits the HTTP status and headers with the first byte, so anything that mutates the response after that point cannot reach the client. This is inherent to streaming, not a Nuxt-specific bug.
+The boundary is the shell flush:
+- **Reaches the client**: mutations from Nuxt and Nitro plugins, which run to completion before rendering begins.
+- **Dropped**: `setResponseStatus()`, `useResponseHeader()`, `useCookie()` writes and h3 `setHeader()`/`appendResponseHeader()` calls made during component rendering (including after an `await` in route middleware or `<script setup>`), since that work happens after the shell is already on the wire.
+To keep a response mutation, move it into a plugin, or opt the route out of streaming:
+- `routeRules: { '/path': { streaming: false } }`: static, per route.
+- the `render:route` hook with `ctx.prefersStream = false`: runtime, per request (e.g. for routes that conditionally set a 404).
+In development the streaming handler logs a warning naming the dropped mutations and the route, so these never fail silently.
+::
+::note
+If an error occurs during streaming after the HTTP status is already committed, `payload.error` is set and the closing tags are still emitted as a well-formed document so the client picks up the error during hydration and renders the error page. Errors thrown before the shell flushes fall through to the buffered error renderer with the correct status code.
+::
+::note
+**Route styles are streamed, JS hints are entry-only.** The shell is flushed before the route renders, so its `<head>` carries entry-chunk styles and hints only. Once render registers the page and layout modules, their CSS is streamed straight after the shell (inlined as `<style>` when `inlineStyles` is enabled, otherwise as stylesheet links), so page, layout, and top-level async-component styles arrive before the body paints (nested async components are a FOUC caveat, covered below). Route-specific JS chunks are not preloaded from the shell; the browser discovers them after parsing the entry script. Streaming improves TTFB on every route; LCP gains are largest on routes whose JS overlaps the entry chunk.
+::
+::note
+**Component islands are compatible with streaming.** Island slot content and selective-client (`nuxt-client`) components are normally stitched into the HTML in a post-render pass, which is impossible once the body has streamed past the island anchors. Instead, the renderer emits each island teleport as an inert `<template>` at the end of the document and relocates it into place with an inline script that runs before hydration. This is transparent to app code. The exception is apps built with `features.noScripts` and island components, which fall back to the buffered renderer since the relocation script cannot run.
+::
+### Module hooks
+Modules participate in the streaming response via the existing `render:html` hook (now with a `streaming: true` flag on the second argument) plus a per-request decision hook and two streaming-only hooks:
+- **`render:route`** fires once per request before rendering begins, for every render (streaming enabled or not). Read `ctx.canStream` to see whether streaming is possible for the route, and set `ctx.prefersStream = false` to force buffered rendering for this request, e.g. based on a cookie, auth state, or A/B bucket. The renderer streams only when `canStream && prefersStream`. This is the runtime escape hatch for the static `routeRules` / `botRegex` config.
+- **`render:html`** fires once, before the shell flushes, with `streaming: true` on its second argument. Mutations to `htmlAttrs`, `head`, `bodyAttrs`, and `bodyPrepend` reach the wire. Mutations to `body`/`bodyAppend` are dropped, since the body is about to stream (a dev-mode warning is emitted). Modules that only mutate head fields (CSP injection, OG tags, analytics meta) work in streaming with no code changes.
+- **`render:html:chunk`** fires for each chunk produced by the renderer before it is enqueued. Mutate `ctx.chunk: Uint8Array` to transform bytes (e.g. nonce injection); read `ctx.index` to identify the first chunk vs. subsequent ones.
+- **`render:html:close`** fires after the body stream completes, before closing tags. Mutate `ctx.bodyAppend: string[]` to inject final markup (end-of-body analytics tags, server-rendered debug widgets, etc.).
+```ts
+// modules/streaming-csp/src/runtime/server-plugin.ts
+import { defineNitroPlugin } from '#imports'
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('render:html', (ctx, { event }) => {
+    const nonce = event.context.cspNonce
+    if (!nonce) { return }
+    // Works for both streaming (pre-shell) and buffered (post-render) paths.
+    for (let i = 0; i < ctx.head.length; i++) {
+      ctx.head[i] = ctx.head[i].replace(/<script(?![^>]*\snonce=)/g, `<script nonce="${nonce}"`)
+    }
+  })
+})
+```
+::note
+**CSP nonce.** The streaming renderer emits several inline scripts and styles that bypass unhead: the bootstrap queue, the IIFE, suspense head pushes, island-teleport relocation, and route `<style>` blocks. If a `nonce` is present on the rendered head scripts, the renderer reuses it on all of them automatically, so a strict `script-src`/`style-src 'nonce-…'` policy does not block streaming. A module only needs to put the nonce on the head scripts (as above); the `render:html:chunk` hook remains available for stamping scripts that components render into the body.
+::
+::warning
+**Dev-mode FOUC for SFC styles:** in development, Vite serves SFC `<style>` blocks as JavaScript modules that inject styles client-side after the module evaluates, with no corresponding `<link>` in the shell. With streaming, the browser starts painting the streamed DOM before those style-injection modules run, so SFC-defined styles flash unstyled briefly.
+Workaround: put paint-critical styles in a global CSS file registered via `css: ['~/assets/main.css']`. Global CSS files are emitted as `<link rel="stylesheet">` in the shell `<head>` and apply before body content streams. SFC `<style>` blocks remain fine for component-scoped styling that doesn't gate the initial paint.
+Production builds extract all styles to real CSS files (or inline via `features.inlineStyles`), so this only affects `nuxt dev`. Validate streaming visuals against `nuxt build && nuxt preview`.
+::
+::warning
+**Production FOUC for nested async components:** the renderer inlines route CSS in a chunk sent straight after the shell. It can only inline the styles for components whose modules are already registered at that point: the page, the layout, and any async component placed directly inside a `<Suspense>` boundary (Vue instantiates those eagerly when render begins).
+An async component that is rendered *inside another async component* is instantiated only once its parent resolves, after the first chunk has streamed. Its SFC `<style>` misses the post-shell styles chunk and is emitted in the closing HTML instead, behind the component's own DOM. The browser paints that component unstyled until the final chunk arrives.
+Avoid it by keeping paint-critical styling out of deeply nested async components:
+- Put styles that gate the initial paint in a global CSS file (`css: ['~/assets/main.css']`); these reach the shell `<head>`.
+- Style with utility classes (Tailwind, UnoCSS): utility CSS lives in the entry stylesheet, not per-component `<style>` blocks.
+- Keep async components that own paint-critical `<style>` directly under a `<Suspense>` boundary rather than nested behind another async parent.
+- Or opt the route out of streaming with `routeRules: { '/path': { streaming: false } }`.
+Non-paint-critical scoped styles on nested async components are fine: the brief flash only matters for above-the-fold content.
+::

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29662437.89c933ea",
+  "version": "5.0.0-29664396.5668d45c",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",