Hydration: Event Replay & inkrementell

Wenn die Seite fertig vom Server gerendert ankommt (SSR oder Prerendering), hat der Browser bereits das komplette DOM. Ohne Hydration würde Angular wie in einer CSR-Anwendung starten: Es würde dieses DOM wegwerfen und neu aufbauen — mit sichtbarem Flackern, kaputtem LCP und Layout Shift. Hydration bedeutet, dass Angular das vorhandene DOM durchläuft, mit dem Komponentenbaum abgleicht und wiederverwendet: Es verbindet die Bindings und hängt die Listener an die bereits existierenden Knoten.

Darauf aufbauend gibt es zwei Optimierungen: Event Replay — Klicks vor der Hydration gehen nicht verloren — und inkrementelle Hydration — Teile der Seite bleiben statisches HTML, ohne geladenes JS, bis sie wirklich gebraucht werden.

Was die Hydration Schritt für Schritt macht

Auf dem Server annotiert Angular nach dem Rendern das HTML, damit es später „wiedergefunden“ werden kann: das Attribut ngh auf jedem Komponenten-Host (ein Index in die Hydration-Daten), Anker-Kommentare für @if/@for/@defer, ein HTML-Kommentar nghm als Integritätsmarker, jsaction auf den Elementen mit Listenern und ein <script id="ng-state"> mit den Hydration-Daten (__nghData__) und den HTTP-Responses aus dem Transfer Cache.

@Component({
  selector: 'app-product-card',
  template: `
    <h2>{{ product().name }}</h2>
    @if (product().stock > 0) {
      <button (click)="addToCart()">In den Warenkorb</button>
    }
  `,
})
export class ProductCard {
  readonly product = input.required<Product>();
  addToCart() { /* ... */ }
}

Im Browser erzeugt Angular beim Bootstrap keine Knoten mehr: Es sucht die vorhandenen anhand der Annotationen. Für jeden Knoten prüft es Typ und Tag (nicht den Text) und hängt die Listener an. Ein abweichender Text ist kein Fehler — er wird bei der ersten Change Detection einfach überschrieben.

Sobald die Anwendung stabil ist (keine laufenden HTTP-Requests und keine PendingTasks), folgt die letzte Phase: Angular entfernt die Server-Knoten, die niemand beansprucht hat, spielt die Events aus der Warteschlange ab und schaltet den Transfer Cache aus. Deshalb hat eine Anwendung, die nie stabil wird, sichtbare Auswirkungen, selbst wenn das DOM korrekt wiederverwendet wurde.

provideClientHydration und seine Optionen

Wenn du SSR mit ng add @angular/ssr hinzugefügt hast, steht der Provider bereits in app.config.ts. Ohne Argumente bekommst du in v22 das empfohlene Set:

import { ApplicationConfig } from '@angular/core';
import { provideClientHydration } from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    // v22, ohne Argumente:
    //  ✓ nicht-destruktive Hydration (nutzt das DOM des Servers weiter)
    //  ✓ HTTP Transfer Cache (GETs/HEADs vom Server werden im Browser nicht wiederholt)
    //  ✓ inkrementelle Hydration (@defer mit hydrate …) — inklusive Event Replay
    //  ✓ im Dev-Modus: provideStabilityDebugging()
    provideClientHydration(),
  ],
};
// app.config.server.ts ruft mergeApplicationConfig(appConfig, serverConfig) auf,
// der Provider landet also auch auf dem Server — Pflicht, sonst erscheint NG0505.

Der Provider muss auch in der Server-Konfiguration vorhanden sein — die vom CLI generierte app.config.server.ts ruft mergeApplicationConfig(appConfig, serverConfig) auf, er ist also automatisch dabei. Fehlt er, annotiert der Server das HTML nicht, und im Browser wird die Seite komplett neu gerendert (im Dev-Modus mit der Warnung NG0505). Widersprüchliche Kombinationen (zum Beispiel withNoHttpTransferCache() mit withHttpTransferCacheOptions()) werfen im Dev-Modus den Fehler NG05001.

Event Replay

Das Problem: Das HTML des Servers ist lange sichtbar, bevor das JS ankommt (in der Timeline auf der SSR-Seite ist das der gelbe Streifen). Der Nutzer sieht einen Button und drückt ihn — aber der Button hat noch keinen Listener.

Der Mechanismus basiert auf JSAction, einer in Angular integrierten Event-Delegation-Bibliothek:

1. Markieren — bei der Serialisierung setzt der Server jsaction="click:;" auf jedes Element, das im Template einen Listener hat.
2. Abfangen — ein kleines Inline-Skript, direkt nach <body> eingefügt (der Event Contract), lauscht auf body-Ebene auf die auf der Seite verwendeten Event-Typen und hält sie im Speicher.
3. Wiedergeben — nach der Hydration, sobald die Anwendung stabil ist, schickt Angular die gespeicherten Events der Reihe nach an die echten Handler.

Es funktioniert für die nativen Browser-Events (click, mouseover, focusin usw.). Bei der inkrementellen Hydration bleibt der Contract auch nach der Hydration aktiv, sodass er Events in noch dehydrierten Blöcken abfangen kann.

Inkrementelle Hydration mit @defer

Ein normales @defer rendert auf dem Server nur den @placeholder: Die Trigger laufen auf dem Server nicht. Ein hydrate-Trigger ändert das: Der Server lädt die Abhängigkeiten des Blocks und rendert den Hauptinhalt. Im Browser bleibt der Block dehydriert — das HTML ist sichtbar, aber der JS-Chunk der darin enthaltenen Komponenten wird nicht einmal geladen —, bis der Trigger feuert. Dann lädt Angular den Chunk, hydriert den Block und spielt die gespeicherten Events ab.

Zwei praktische Folgen. Erstens: Du kannst @defer above the fold verwenden, ohne Layout Shift, weil der endgültige Inhalt bereits auf dem Bildschirm steht und nicht der Placeholder. Zweitens: Ein Event auf einem Element mit Listener in einem dehydrierten Block löst dessen Hydration aus, egal welcher Trigger deklariert ist — der Klick geht nicht verloren. Die Ausnahme ist hydrate never: Sein Teilbaum wird gar nicht annotiert, es gibt also nichts abzuspielen.

<app-header />                                    <!-- kein @defer: wird beim Bootstrap hydriert -->

@defer (hydrate on interaction) {
  <app-gallery [images]="product().images" />     <!-- JS der Galerie: erst beim ersten Klick -->
} @placeholder {
  <div class="gallery-skeleton"></div>            <!-- nur bei Client-Side-Navigation verwendet -->
}

@defer (hydrate on hover) {
  <app-recommendations [productId]="id()" />
} @placeholder {
  <div class="reco-skeleton"></div>
}

@defer (hydrate on idle) {
  <app-support-chat />
} @placeholder {
  <button>Chat</button>
}

@defer (hydrate on viewport) {
  <app-reviews [productId]="id()" />              <!-- unterhalb des sichtbaren Bereichs: JS, sobald er im Bild erscheint -->
} @placeholder {
  <div class="reviews-skeleton"></div>
}

@defer (hydrate never) {
  <app-footer />                                  <!-- für immer statisches HTML -->
}

Die Hydration-Trigger

@defer (hydrate on idle) { … }                    <!-- requestIdleCallback -->
@defer (hydrate on idle(500)) { … }               <!-- idle, spätestens aber nach 500 ms -->
@defer (hydrate on viewport) { … }                <!-- der Inhalt des Blocks erscheint im Bild -->
@defer (hydrate on viewport({ rootMargin: '200px' })) { … }  <!-- nur literale Optionen -->
@defer (hydrate on interaction) { … }             <!-- click / keydown im Block -->
@defer (hydrate on hover) { … }                   <!-- mouseover / focusin im Block -->
@defer (hydrate on immediate) { … }               <!-- direkt nach dem Rest der Seite -->
@defer (hydrate on timer(2s)) { … }               <!-- ms oder s -->
@defer (hydrate when cartReady()) { … }           <!-- Bedingung aus der Eltern-Komponente -->
@defer (hydrate never) { … }                      <!-- nie; keine anderen Hydrate-Trigger -->
@defer (hydrate on viewport; hydrate on timer(5s)) { … }  <!-- mehrere = einer davon genügt (OR) -->

<!-- ✗ Kompilierfehler -->
@defer (hydrate on interaction(btn)) { … }        <!-- interaction/hover nehmen keine Referenz -->
@defer (hydrate on viewport({ trigger: el })) { … }
@defer (hydrate never; hydrate on idle) { … }     <!-- never schließt jeden anderen Hydrate-Trigger aus -->

Mehrere Trigger am selben Block werden mit „beliebig“ (OR) kombiniert. hydrate when hat eine Einschränkung: Der Ausdruck gehört zur Eltern-Komponente, die selbst hydriert sein muss, damit der Ausdruck ausgewertet werden kann.

Verschachtelte Blöcke

Der Komponentenbaum ist hierarchisch: Ein Kind kann nicht aktiv sein ohne seinen Elternteil. Wenn der Trigger bei einem verschachtelten Block feuert, hydriert Angular die Kette von oben nach unten — zuerst den äußersten dehydrierten Block, dann einen nach dem anderen bis zu dem, der angefragt hat.

@defer (hydrate on interaction) {
  <app-product-tabs />                <!-- 1. zuerst wird die Eltern-Komponente hydriert… -->
  @defer (hydrate on hover) {
    <app-size-guide />                <!-- 2. …dann das Kind, auch wenn der Hover darauf lag -->
  }
}

Hydrate-Trigger bei CSR und Navigation

Hydration ist eine Optimierung des Erstaufrufs von serverseitig gerendertem Inhalt. Wenn der Nutzer dieselbe Seite über Client-Side-Navigation erreicht (ein routerLink) oder die Anwendung gar kein SSR hat, werden die hydrate-Trigger ignoriert: Der Block verhält sich wie ein normales @defer, mit seinem @placeholder und den normalen Triggern. Hast du keinen normalen Trigger angegeben, fügt der Compiler on idle hinzu.

@defer (on interaction; hydrate on viewport) {
  <app-reviews />
} @placeholder {
  <button>Bewertungen anzeigen</button>
}

<!--
  Erstaufruf, auf dem Server gerenderte Seite:
    → der Server rendert <app-reviews /> (nicht den Placeholder)
    → im Browser bleibt es statisches HTML, bis es den Viewport erreicht (hydrate on viewport)

  Client-Side-Navigation (routerLink) oder Anwendung ohne SSR:
    → hydrate on viewport wird ignoriert
    → der @placeholder wird angezeigt, der Block lädt beim Klick (on interaction)
    → ohne normalen Trigger wäre der Standard on idle gewesen
-->

• @placeholder bleibt nötig — beim Erstaufruf mit SSR wird er nicht angezeigt, bei jeder Client-Side-Navigation zur Seite aber schon.
• hydrate never bedeutet „beim Erstaufruf nie JS“. Beim späteren Client-Side-Rendering lädt der Block seine Abhängigkeiten trotzdem, mit dem normalen Trigger.
• In einer Anwendung ohne provideClientHydration() (oder mit withNoIncrementalHydration()) erzeugen Blöcke mit hydrate-Triggern im Dev-Modus die Warnung NG0508.

Mismatch-Fehler

Die Hydration beginnt mit einem Versprechen: Das DOM im Browser ist exakt das, das der Server erzeugt hat, einschließlich Kommentaren und Leerzeichen. Alles, was das Versprechen bricht — der HTML-Parser des Browsers, ein Drittanbieter-Skript, ein CDN, ein anderer Template-Zweig —, endet in einer von drei Situationen: ein Fehler, eine Warnung oder, am heimtückischsten, kein Fehler, aber ein sichtbares erneutes Rendern.

<p class="promo">
  <div>Heute kostenlose Lieferung</div>
</p>

<p class="promo"><div>Heute kostenlose Lieferung</div></p>

<p class="promo"></p><div>Heute kostenlose Lieferung</div><p></p>

NG0500: During hydration Angular expected <div> but the node was not found.

Angular expected this DOM:

  <p class="promo">
    <div>…</div>  <-- AT THIS LOCATION
    …
  </p>

To fix this problem:
  * check the "PromoBanner" component for hydration-related issues
  * check to see if your template has valid HTML structure
  …

ngSkipHydration: der Notausgang

Für eine Komponente, die sich nicht sofort reparieren lässt (typischerweise eine Bibliothek, die direkt ins DOM zeichnet, wie D3), nimmt das Attribut ngSkipHydration auf ihrem Host sie aus der Hydration heraus: Die Komponente und ihre Kinder werden zerstört und neu gerendert, genau wie ohne Hydration. Es funktioniert nur auf Komponenten-Hosts (sonst NG0504), und auf der Root-Komponente deaktiviert es die Hydration für die ganze Anwendung.

<!-- auf dem Host der Komponente, die das DOM direkt manipuliert (z. B. ein D3-Diagramm) -->
<app-sales-chart ngSkipHydration [data]="sales()" />

<!-- ✗ NG0504: nur auf Komponenten-Hosts, nicht auf normalen Elementen -->
<div ngSkipHydration><app-sales-chart [data]="sales()" /></div>

Debugging

• Die Konsole im Dev-Modus: Sobald die Anwendung stabil ist, erscheint eine Zusammenfassung. Siehst du sie nicht, hat die Hydration nicht gestartet (prüfe NG0505).
• Angular DevTools zeigt den Hydration-Zustand jeder Komponente und kann ein Overlay über den hydrierten Teilen einblenden; bei einem Mismatch-Fehler hebt es die verantwortliche Komponente hervor.
• Seitenquelltext vs. Elements: Der Seitenquelltext ist das HTML des Servers, Elements ist das aktuelle DOM. Die Unterschiede zwischen beiden (ein zusätzliches tbody, ein eingeschleustes Banner) sind genau die Ursachen von NG0500.
• JavaScript ausschalten in den DevTools und neu laden: Du siehst genau, was der Nutzer vor der Hydration bekommt.
• NG0506: provideStabilityDebugging() listet die Tasks auf, die die Anwendung instabil halten (mit Zone.js zusätzlich zone.js/plugins/task-tracking importieren).
• preserveWhitespaces muss in tsconfig.app.json und tsconfig.server.json denselben Wert haben; der Standard (false) ist der empfohlene.

Angular hydrated 14 component(s) and 212 node(s), 0 component(s) were skipped.
5 defer block(s) were configured to use incremental hydration.
Learn more at https://angular.dev/guide/hydration.

Wann ja, wann nein

Häufige Stolperfallen

• Ungültiges HTML: ein <div> in einem <p>, ein <a> in einem <a>, eine Tabelle ohne <tbody>. Validiere das Template; der Browser „repariert“ HTML anders, als der Server es geschrieben hat.
• Unterschiedliche Werte auf Server und Client (Date.now(), Math.random(), generierte IDs, Zeitzonen): kein Fehler, aber der Text ändert sich vor den Augen des Nutzers. Übertrage den Wert mit TransferState.
• Drittanbieter-Skripte (Analytics, Consent, Chat), die das DOM vor der Hydration verändern: Lade sie danach, mit afterNextRender.
• withEventReplay() und withIncrementalHydration() „sicherheitshalber“ stehen gelassen in v22: Das erste ist überflüssig, das zweite deprecated. Ein schlichtes provideClientHydration() reicht.
• Ein entfernter @placeholder bei den Blöcken mit hydrate, weil „man ihn ja eh nicht sieht“: Bei Client-Side-Navigation sieht man ihn.
• Personenbezogene Daten im Transfer Cache: Responses landen im HTML. Requests mit Authorization/Cookie sind standardmäßig ausgeschlossen — nimm sie nicht ohne Grund mit includeRequestsWithAuthHeaders auf; nutze filter oder transferCache: false.
• Ein CDN mit HTML-Minifizierung, das die Kommentare entfernt → NG0507 auf jeder Seite.

Spickzettel

// ── Config (app.config.ts; landet über mergeApplicationConfig auch auf dem Server)
provideClientHydration();                                     // v22: DOM + Transfer Cache + inkrementell + Replay
provideClientHydration(withNoIncrementalHydration(), withEventReplay());
provideClientHydration(withI18nSupport());
provideClientHydration(withHttpTransferCacheOptions({ filter, includeHeaders, includePostRequests }));
provideClientHydration(withNoHttpTransferCache());
http.get(url, { transferCache: false });                      // Opt-out pro Request

// ── Template
// @defer (hydrate on idle | idle(ms) | viewport | viewport({ rootMargin }) | interaction | hover | immediate | timer(2s))
// @defer (hydrate when cond)      @defer (hydrate never)      @defer (on idle; hydrate on viewport)
// <app-chart ngSkipHydration />   host: { ngSkipHydration: 'true' }   ← letzter Ausweg

// ── Fehler
// NG0500 anderer Knoten   NG0501 Geschwisterknoten fehlen   NG0502 Knoten fehlt   NG0503 projizierte Knoten außerhalb von Angular erzeugt
// NG0504 ngSkipHydration auf Nicht-Komponente   NG0505 Annotationen fehlen (Provider fehlt auf dem Server)
// NG0506 die Anwendung wird nicht innerhalb von 10 s stabil   NG0507 HTML nach dem Server verändert (Kommentare entfernt)
// NG0508 Hydrate-Trigger ohne aktive inkrementelle Hydration