feat: add support for Streaming SSR

apps/docs-app/docs/features/server/streaming-ssr.md

@@ -0,0 +1,122 @@
+# Streaming SSR
+
+Analog supports progressive streaming server-side rendering, flushing the
+response to the browser as the app renders instead of buffering the whole
+document until it is complete.
+
+The document head is sent immediately, each `@defer (hydrate …)` block is sent
+the moment it resolves on the server, and the authoritative document arrives
+last — so a slow block never holds back the rest of the page.
+
+:::info Experimental
+
+Streaming SSR is experimental and opt-in. It requires **Angular 21 or later**
+and builds on [incremental hydration](https://angular.dev/guide/incremental-hydration).
+The default buffered [Server Side Rendering](/docs/features/server/server-side-rendering)
+path is unchanged.
+
+:::
+
+## Enabling streaming
+
+Enable the `experimental.streaming` option in your Vite config:
+
+```ts
+// vite.config.ts
+import analog from '@analogjs/platform';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [analog({ experimental: { streaming: true } })],
+});
+```
+
+Then use `renderStream` instead of `render` in `main.server.ts`:
+
+```ts
+// src/main.server.ts
+import { renderStream } from '@analogjs/router/server';
+import { config } from './app/app.config.server';
+import { AppComponent } from './app/app.component';
+
+export default renderStream(AppComponent, config);
+```
+
+Streaming builds on incremental hydration, so enable it in your client
+providers. On Angular 21 use `withIncrementalHydration()`; on Angular 22+ it is
+enabled by default with `provideClientHydration()`:
+
+```ts
+// src/app/app.config.ts
+import {
+  provideClientHydration,
+  withIncrementalHydration,
+} from '@angular/platform-browser';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideClientHydration(withIncrementalHydration()),
+    // ...
+  ],
+};
+```
+
+## Streaming deferred blocks
+
+Content that should stream progressively goes in a `@defer` block with a
+`hydrate` trigger. Each block is rendered eagerly on the server, streamed as it
+resolves, and hydrated on the client when its trigger fires:
+
+```markup
+<h1>Dashboard</h1>
+
+@defer (hydrate on immediate) {
+  <app-activity-feed />
+} @placeholder {
+  <p>Loading activity…</p>
+}
+
+@defer (hydrate on viewport) {
+  <app-recommendations />
+} @placeholder {
+  <p>Loading recommendations…</p>
+}
+```
+
+A block backed by asynchronous data (for example an
+[`httpResource`](https://angular.dev/guide/http/http-resource)) keeps the render
+pending until its data resolves, so the block streams with its final content and
+the page's time-to-first-byte is unaffected.
+
+## Title and meta
+
+Because the document head is flushed before the app renders, a title or meta set
+during render (via the `Title`/`Meta` services or route metadata) is applied to
+the streamed document once the render completes, before hydration runs. Search
+engine crawlers are served a buffered render with a fully resolved head instead
+of the streamed shell.
+
+## Opting a route out of streaming
+
+Disable streaming for specific routes with a `streaming: false` route rule, the
+same way `ssr: false` disables SSR. Matching routes fall back to a buffered
+render (no streaming, but SSR and hydration still work):
+
+```ts
+// vite.config.ts
+import analog from '@analogjs/platform';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    analog({
+      experimental: { streaming: true },
+      nitro: {
+        routeRules: {
+          '/report': { streaming: false },
+        },
+      },
+    }),
+  ],
+});
+```

apps/docs-app/sidebars.js

@@ -118,6 +118,12 @@ const sidebars = {
               label: 'Overview',
               key: 'server-side-rendering-overview',
             },
+            {
+              type: 'doc',
+              id: 'features/server/streaming-ssr',
+              label: 'Streaming SSR',
+              key: 'streaming-ssr',
+            },
           ],
         },
         {

apps/streaming-app/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Analog Streaming SSR</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <streaming-root></streaming-root>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

apps/streaming-app/project.json

@@ -0,0 +1,51 @@
+{
+  "name": "streaming-app",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "apps/streaming-app/src",
+  "prefix": "analogjs",
+  "tags": [],
+  "implicitDependencies": ["platform", "router"],
+  "targets": {
+    "build": {
+      "executor": "@nx/vite:build",
+      "outputs": [
+        "{options.outputPath}",
+        "{workspaceRoot}/dist/apps/streaming-app/.nitro",
+        "{workspaceRoot}/dist/apps/streaming-app/ssr",
+        "{workspaceRoot}/dist/apps/streaming-app/analog"
+      ],
+      "options": {
+        "configFile": "apps/streaming-app/vite.config.ts",
+        "outputPath": "dist/apps/streaming-app/client"
+      },
+      "defaultConfiguration": "production",
+      "configurations": {
+        "development": {
+          "mode": "development"
+        },
+        "production": {
+          "sourcemap": false,
+          "mode": "production"
+        }
+      }
+    },
+    "serve": {
+      "executor": "@nx/vite:dev-server",
+      "defaultConfiguration": "development",
+      "options": {
+        "buildTarget": "streaming-app:build",
+        "port": 3200
+      },
+      "configurations": {
+        "development": {
+          "buildTarget": "streaming-app:build:development",
+          "hmr": true
+        },
+        "production": {
+          "buildTarget": "streaming-app:build:production"
+        }
+      }
+    }
+  }
+}

apps/streaming-app/src/app/app.component.ts

@@ -0,0 +1,10 @@
+import { Component } from '@angular/core';
+import { RouterOutlet } from '@angular/router';
+
+@Component({
+  selector: 'streaming-root',
+  standalone: true,
+  imports: [RouterOutlet],
+  template: `<router-outlet></router-outlet>`,
+})
+export class AppComponent {}

apps/streaming-app/src/app/app.config.server.ts

@@ -0,0 +1,10 @@
+import { mergeApplicationConfig, ApplicationConfig } from '@angular/core';
+import { provideServerRendering } from '@angular/platform-server';
+
+import { appConfig } from './app.config';
+
+const serverConfig: ApplicationConfig = {
+  providers: [provideServerRendering()],
+};
+
+export const config = mergeApplicationConfig(appConfig, serverConfig);

apps/streaming-app/src/app/app.config.ts

@@ -0,0 +1,22 @@
+import { provideFileRouter, requestContextInterceptor } from '@analogjs/router';
+import {
+  provideHttpClient,
+  withFetch,
+  withInterceptors,
+} from '@angular/common/http';
+import { ApplicationConfig } from '@angular/core';
+import {
+  provideClientHydration,
+  withIncrementalHydration,
+} from '@angular/platform-browser';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withFetch(),
+      withInterceptors([requestContextInterceptor]),
+    ),
+    provideClientHydration(withIncrementalHydration()),
+    provideFileRouter(),
+  ],
+};

apps/streaming-app/src/app/blocks/fast-a.component.ts

@@ -0,0 +1,17 @@
+import { Component, signal } from '@angular/core';
+
+@Component({
+  selector: 'app-fast-a',
+  standalone: true,
+  template: `<section class="block-a">
+    Block A — deferred (fast, no async) + incrementally hydrated. count =
+    {{ count() }}
+    <button class="btn-a" (click)="inc()">A+</button>
+  </section>`,
+})
+export class FastA {
+  count = signal(41);
+  inc() {
+    this.count.set(this.count() + 1);
+  }
+}

apps/streaming-app/src/app/blocks/shell-status.component.ts

@@ -0,0 +1,20 @@
+import { Component, signal } from '@angular/core';
+
+// Eager, non-@defer component: it renders as part of the app body (so it lands
+// in the authoritative tail, not a deferred preview) and — unlike the @defer
+// blocks — hydrates immediately on bootstrap rather than via an incremental
+// hydration trigger. Covers the ordinary, non-deferred hydration path.
+@Component({
+  selector: 'app-shell-status',
+  standalone: true,
+  template: `<p class="block-eager">
+    Eager component — rendered in the shell, hydrated immediately. n = {{ n() }}
+    <button class="btn-eager" (click)="inc()">E+</button>
+  </p>`,
+})
+export class ShellStatus {
+  n = signal(7);
+  inc() {
+    this.n.set(this.n() + 1);
+  }
+}

apps/streaming-app/src/app/blocks/slow-b.component.ts

@@ -0,0 +1,25 @@
+import { Component, linkedSignal } from '@angular/core';
+import { httpResource } from '@angular/common/http';
+
+@Component({
+  selector: 'app-slow-b',
+  standalone: true,
+  template: `<aside class="block-b">
+    Block B — deferred + incrementally hydrated. label = {{ label() }}
+    <button class="btn-b" (click)="toggle()">B!</button>
+  </aside>`,
+})
+export class SlowB {
+  // Real per-request data fetch against a slow API route. During SSR the render
+  // stays unstable until this resolves, so the authoritative document is the
+  // last thing flushed — the head and Block A have already streamed.
+  private data = httpResource<{ label: string }>(() => '/api/slow-b');
+
+  // Seed a writable signal from the resolved data; the click can still override
+  // it locally, and it re-seeds if the source ever changes.
+  label = linkedSignal(() => this.data.value()?.label ?? 'loading');
+
+  toggle() {
+    this.label.set(this.label() === 'summer' ? 'winter' : 'summer');
+  }
+}