Nuxt 4.5 SSR Streaming: The Route Rules That Disable It

Your team flips experimental.ssrStreaming: true in nuxt.config.ts, loads the homepage, and Time to First Byte drops from 1.8 seconds to 40 milliseconds. Everyone's thrilled. Someone ships it to every route in the app. Two days later, a teammate asks why the pricing page — behind a cache route rule, same layout, same components — didn't get any faster. Then a third teammate reports pages crashing in production with an error nobody on the team has seen before: ERR_HTTP_HEADERS_SENT.

Nothing here is a Nuxt bug. It's six route rules quietly opting themselves out of streaming, and one very normal pattern — a request interceptor that sets a cookie — running straight into the one thing streaming doesn't let you do anymore: change your mind about the response after you've already sent the start of it.

This article is written against Nuxt 4.5 (verified against the 4.5.2 release on npm's latest tag; experimental.ssrStreaming shipped in 4.5.0, released July 18, 2026). Nuxt 3 reached end-of-life on July 31, 2026, so if you're still on it, this feature doesn't exist for you yet — it's 4.5-only, and still explicitly experimental: opt-in, and the options around it (we'll get to botRegex) are young enough that the Nuxt team is still renaming them for clarity.

You've deployed a Nuxt app, you've used routeRules in nuxt.config.ts for at least one of cache, prerender, or ssr: false, and you know roughly what "Nuxt renders on the server, then hydrates on the client" means. If that last part is fuzzy, read the hydration mismatch episode first — this article assumes you already have that mental model and builds the streaming layer on top of it.

Here's the naive version of what that team did:

It works exactly as advertised on a plain page: no route rule, no redirect logic, nothing fancy — just a component tree that fetches some data and renders. Time to First Byte on that page drops hard, because Nuxt no longer waits for the whole page to finish rendering before it sends anything.

Then someone checks /pricing, which has this in the same config file:

Same flag, same app, zero difference in TTFB. Not a regression — Nuxt silently buffered that route instead of streaming it, because cache is one of six route rules that disable streaming automatically. Nobody configured that. It isn't documented in the obvious place you'd look (the route rule itself). It's a consequence of what streaming is, and once you see that, the whole fallback list stops looking arbitrary.

The mental model: SSR streaming doesn't change what Nuxt renders. It changes when the response is allowed to be final.

That's the entire feature. The speed win is real: the browser gets bytes — and can start painting and fetching sub-resources — while Nuxt is still working on the rest of the page. But committing the headers early has a one-way-door property: once the shell has flushed, Nuxt cannot change its mind about the response. No new status code, no new header, no new cookie, no "actually, redirect instead."

Read the fallback list through that lens and every entry explains itself: each of the six rules needs to make a decision about the whole response that can only be made correctly before anything is sent. Streaming removes the "before" — so Nuxt just doesn't stream those routes.

The flag lives under experimental because the feature is new and still finding its edges:

Key concept: this is a global switch, but "global" doesn't mean "every route behaves identically" — it means every route is now eligible for streaming, and Nuxt decides per-request whether a given route actually qualifies.

Per the official 4.5 release notes, routes carrying any of these routeRules automatically fall back to the buffered renderer, with no warning and no error:

Notice the pattern: every rule on this list needs to produce one finished, final thing — a cached payload, a static file, a redirect, a client-only shell — and streaming's whole mechanism is sending an unfinished thing on purpose. The two ideas are structurally incompatible, not just awkwardly combined.

Streaming has one more built-in exception that isn't a route rule: bots and crawlers get the buffered response too, automatically, so search engines still receive one complete HTML document instead of a stream they may not handle well:

And if you have a route that qualifies for streaming by the rules above, but you don't trust it yet — maybe it runs business logic you haven't audited (more on that next) — you can force it to stay buffered with its own route rule:

Key concept: the six-rule fallback list is Nuxt protecting you automatically. streaming: false is you protecting yourself manually, for routes the automatic list doesn't know are risky.

This is the part the release notes describe as a caveat and real apps discovered as an outage. In 2026, the community auth module nuxt-auth-sanctum shipped a response interceptor that — like a lot of auth and session code — tried to set a cookie on the outgoing response during SSR. Under streaming, that interceptor ran after the shell had already flushed. The result, reported as issue #669: every SSR request on every page using the module threw ERR_HTTP_HEADERS_SENT, the render died mid-stream, and the visitor got back an HTTP 200 with a dead, partially-written page — not even a clean error, because the status code was already committed as a success before anything went wrong. The maintainers shipped a fix in PR #702 that made the module streaming-aware.

That's the general shape of the failure, and it isn't specific to that one module: anything that tries to set a cookie, a header, or a status code from inside your render — an auth interceptor, an A/B testing plugin, a geo-redirect check — is a candidate for this exact crash, the instant you turn streaming on for a route it runs on.

No. It changes how Nuxt delivers a route's response. Your routeRules are unchanged; Nuxt just reads them to decide, per route, whether it's allowed to stream or must fall back to buffering.

Because cache is one of the six route rules that force buffering. Streaming literally does not apply to that route — look for the TTFB win on a route with no cache/isr/swr/redirect/noScripts/ssr: false rule instead.

No — that's not a setting Nuxt exposes, and for good reason: caching a response requires one finished response to cache, which streaming doesn't produce. You can go the other direction, though: force a normally-streamable route to stay buffered with routeRules: { '/path': { streaming: false } }.

No. It lives under experimental in nuxt.config.ts, it's opt-in, and related option names (like botRegex) were still being refined after the initial 4.5.0 release. Treat it as something to pilot, not something to assume is final.

No, by design. Nuxt detects bots and crawlers via botRegex and serves them the old buffered, fully-rendered HTML — streaming is specifically for real browsers that can render progressively.

ERR_HTTP_HEADERS_SENT — Node's standard error for writing headers after they've already been sent. Under streaming, that moment arrives as soon as the shell flushes, which is much earlier in the request than most response-mutating code expects.

Streaming is the first Nuxt feature that makes you think about the response as a timeline instead of a single object, and that timeline is exactly what makes the fallback list make sense instead of feeling arbitrary. Next time a route doesn't speed up the way you expected, you now know exactly which line in routeRules to go check first — and what to look for in your own code before you widen the rollout.

Have you hit the ERR_HTTP_HEADERS_SENT version of this, or a route that silently didn't stream when you expected it to? Drop it in the comments — it's early enough in this feature's life that real reports like these are still shaping how it gets documented.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Think it clicked? Take the 9-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: