Hidratare: event replay & incremental

Când pagina vine randată de pe server (SSR sau prerender), browserul are deja DOM-ul complet. Fără hidratare, Angular ar porni ca într-o aplicație CSR: ar arunca acel DOM și l-ar construi din nou — clipire vizibilă, LCP stricat, layout shift. Hidratarea înseamnă că Angular parcurge DOM-ul existent, îl potrivește cu arborele de componente și îl refolosește: leagă binding-urile și atașează listenerii la nodurile care există deja.

Peste ea s-au construit două optimizări: event replay — click-urile făcute înainte de hidratare nu se pierd — și hidratarea incrementală — bucăți din pagină rămân HTML static, fără JS descărcat, până când chiar e nevoie de ele.

Ce face hidratarea, pas cu pas

Pe server, după randare, Angular adnotează HTML-ul ca să poată fi „regăsit” mai târziu: atributul ngh pe gazda fiecărei componente (un index în datele de hidratare), comentarii-ancoră pentru @if/@for/@defer, un comentariu HTML nghm ca marcaj de integritate, jsaction pe elementele care au listeneri și un <script id="ng-state"> cu datele de hidratare (__nghData__) și răspunsurile HTTP din transfer cache.

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

În browser, la bootstrap, Angular nu mai creează noduri: le caută pe cele existente, folosind adnotările. Pentru fiecare nod verifică tipul și tag-ul (nu și textul) și atașează listenerii. Un text diferit nu e eroare — e pur și simplu suprascris la primul change detection.

După ce aplicația devine stabilă (fără request-uri HTTP și PendingTasks în curs), urmează etapa de final: Angular șterge nodurile de pe server pe care nu le-a revendicat nimeni, reia evenimentele din coadă și oprește transfer cache-ul. De aceea o aplicație care nu devine stabilă are efecte vizibile chiar dacă DOM-ul a fost refolosit corect.

provideClientHydration și opțiunile

Dacă ai adăugat SSR cu ng add @angular/ssr, provider-ul e deja în app.config.ts. Fără argumente, în v22, primești setul recomandat:

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

export const appConfig: ApplicationConfig = {
  providers: [
    // v22, fără argumente:
    //  ✓ hidratare non-distructivă (refolosește DOM-ul serverului)
    //  ✓ HTTP transfer cache (GET/HEAD făcute pe server nu se repetă în browser)
    //  ✓ hidratare incrementală (@defer cu hydrate …) — include event replay
    //  ✓ în dev mode: provideStabilityDebugging()
    provideClientHydration(),
  ],
};
// app.config.server.ts face mergeApplicationConfig(appConfig, serverConfig),
// deci provider-ul ajunge și pe server — obligatoriu, altfel apare NG0505.

Provider-ul trebuie să existe și în config-ul de server — app.config.server.ts generat de CLI face mergeApplicationConfig(appConfig, serverConfig), deci e acolo automat. Dacă lipsește, serverul nu adnotează HTML-ul, iar în browser pagina e re-randată de la zero (în dev mode, cu avertismentul NG0505). Combinațiile contradictorii (de exemplu withNoHttpTransferCache() cu withHttpTransferCacheOptions()) aruncă eroarea NG05001 în dev mode.

Event replay

Problema: HTML-ul de pe server e vizibil cu mult înainte să sosească JS-ul (în timeline-ul de pe pagina SSR e banda galbenă). Utilizatorul vede un buton și apasă — dar butonul nu are încă niciun listener.

Mecanismul se bazează pe JSAction, o bibliotecă de event delegation integrată în Angular:

1. Marcare — la serializare, serverul pune jsaction="click:;" pe fiecare element care are un listener în template.
2. Captare — un script mic, inline, injectat imediat după <body> (event contract), ascultă la nivelul body tipurile de evenimente folosite în pagină și le ține în memorie.
3. Reluare — după hidratare, când aplicația devine stabilă, Angular trimite evenimentele din coadă, în ordine, handler-elor reale.

Funcționează pentru evenimente native ale browserului (click, mouseover, focusin etc.). Cu hidratarea incrementală, contractul rămâne activ și după hidratare, ca să prindă evenimentele din blocurile încă deshidratate.

Hidratare incrementală cu @defer

Un @defer obișnuit randează pe server doar @placeholder-ul: trigger-ele nu rulează pe server. Un trigger hydrate schimbă asta: serverul încarcă dependențele blocului și randează conținutul principal. În browser, blocul rămâne deshidratat — HTML-ul se vede, dar chunk-ul JS al componentelor din el nici măcar nu e descărcat — până când se declanșează trigger-ul. Atunci Angular descarcă chunk-ul, hidratează blocul și reia evenimentele din coadă.

Două consecințe practice. Prima: poți pune @defer și deasupra fold-ului fără layout shift, pentru că pe ecran e deja conținutul final, nu placeholder-ul. A doua: un eveniment pe un element cu listener dintr-un bloc deshidratat îi declanșează hidratarea, oricare ar fi trigger-ul declarat — click-ul nu se pierde. Excepție face hydrate never: subarborele lui nu e deloc adnotat, deci nu are ce relua.

<app-header />                                    <!-- fără @defer: hidratat la bootstrap -->

@defer (hydrate on interaction) {
  <app-gallery [images]="product().images" />     <!-- JS-ul galeriei: abia la primul click -->
} @placeholder {
  <div class="gallery-skeleton"></div>            <!-- folosit doar la navigare client-side -->
}

@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()" />              <!-- sub fold: JS când intră în ecran -->
} @placeholder {
  <div class="reviews-skeleton"></div>
}

@defer (hydrate never) {
  <app-footer />                                  <!-- HTML static pentru totdeauna -->
}

Trigger-ele de hidratare

@defer (hydrate on idle) { … }                    <!-- requestIdleCallback -->
@defer (hydrate on idle(500)) { … }               <!-- idle, dar cel târziu după 500 ms -->
@defer (hydrate on viewport) { … }                <!-- conținutul blocului intră în ecran -->
@defer (hydrate on viewport({ rootMargin: '200px' })) { … }  <!-- doar opțiuni literale -->
@defer (hydrate on interaction) { … }             <!-- click / keydown în bloc -->
@defer (hydrate on hover) { … }                   <!-- mouseover / focusin în bloc -->
@defer (hydrate on immediate) { … }               <!-- imediat după restul paginii -->
@defer (hydrate on timer(2s)) { … }               <!-- ms sau s -->
@defer (hydrate when cartReady()) { … }           <!-- condiție din componenta părinte -->
@defer (hydrate never) { … }                      <!-- niciodată; fără alte hydrate triggers -->
@defer (hydrate on viewport; hydrate on timer(5s)) { … }  <!-- mai multe = oricare (OR) -->

<!-- ✗ erori de compilare -->
@defer (hydrate on interaction(btn)) { … }        <!-- interaction/hover nu primesc referință -->
@defer (hydrate on viewport({ trigger: el })) { … }
@defer (hydrate never; hydrate on idle) { … }     <!-- never exclude orice alt hydrate trigger -->

Mai multe trigger-e pe același bloc se combină cu „oricare” (OR). hydrate when are o limită: expresia aparține componentei părinte, care trebuie să fie ea însăși hidratată ca expresia să poată fi evaluată.

Blocuri imbricate

Arborele de componente e ierarhic: un copil nu poate fi activ fără părintele lui. Dacă trigger-ul se declanșează pe un bloc imbricat, Angular hidratează lanțul de sus în jos — întâi blocul deshidratat cel mai de sus, apoi pe rând până la cel care a cerut.

@defer (hydrate on interaction) {
  <app-product-tabs />                <!-- 1. se hidratează întâi părintele… -->
  @defer (hydrate on hover) {
    <app-size-guide />                <!-- 2. …apoi copilul, chiar dacă hover-ul a fost pe el -->
  }
}

Hydrate triggers în CSR și la navigare

Hidratarea e o optimizare a încărcării inițiale de conținut randat pe server. Când utilizatorul ajunge la aceeași pagină prin navigare client-side (un routerLink), sau când aplicația nu are SSR deloc, trigger-ele hydrate sunt ignorate: blocul se comportă ca un @defer obișnuit, cu @placeholder și trigger-ele normale. Dacă nu ai pus niciun trigger normal, compilatorul adaugă on idle.

@defer (on interaction; hydrate on viewport) {
  <app-reviews />
} @placeholder {
  <button>Arată recenziile</button>
}

<!--
  Încărcarea inițială, pagină randată pe server:
    → serverul randează <app-reviews /> (nu placeholder-ul)
    → în browser rămâne HTML static până intră în viewport (hydrate on viewport)

  Navigare client-side (routerLink) sau aplicație fără SSR:
    → hydrate on viewport e ignorat
    → se vede @placeholder, blocul se încarcă la click (on interaction)
    → fără trigger normal, implicit ar fi fost on idle
-->

• @placeholder rămâne necesar — nu apare la încărcarea inițială cu SSR, dar apare la orice navigare client-side spre pagină.
• hydrate never înseamnă „niciodată JS la încărcarea inițială”. La o randare client-side ulterioară, blocul își descarcă totuși dependențele, cu trigger-ul normal.
• Într-o aplicație fără provideClientHydration() (sau cu withNoIncrementalHydration()), blocurile cu trigger-e hydrate produc în dev mode avertismentul NG0508.

Erori de nepotrivire

Hidratarea pornește de la o promisiune: DOM-ul din browser e exact cel produs de server, inclusiv comentariile și spațiile. Orice lucru care încalcă promisiunea — parser-ul HTML al browserului, un script terț, un CDN, o ramură de template diferită — se termină într-una din trei situații: eroare, avertisment sau, cel mai perfid, nicio eroare dar o re-randare vizibilă.

<p class="promo">
  <div>Livrare gratuită azi</div>
</p>

<p class="promo"><div>Livrare gratuită azi</div></p>

<p class="promo"></p><div>Livrare gratuită azi</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: ieșirea de urgență

Pentru o componentă care nu poate fi reparată imediat (tipic: o librărie care desenează direct în DOM, ca D3), atributul ngSkipHydration pe gazda ei o scoate din hidratare: componenta și copiii ei sunt distruși și re-randați, exact ca fără hidratare. Funcționează doar pe gazde de componente (altfel NG0504), iar pus pe componenta rădăcină dezactivează hidratarea pentru toată aplicația.

<!-- pe gazda componentei care manipulează DOM-ul direct (ex. un grafic D3) -->
<app-sales-chart ngSkipHydration [data]="sales()" />

<!-- ✗ NG0504: doar pe gazde de componente, nu pe elemente obișnuite -->
<div ngSkipHydration><app-sales-chart [data]="sales()" /></div>

Debugging

• Consola, în dev mode: după ce aplicația devine stabilă apare un rezumat. Dacă nu-l vezi, hidratarea nu a pornit (verifică NG0505).
• Angular DevTools arată starea de hidratare a fiecărei componente și poate activa un overlay peste părțile hidratate; la o eroare de nepotrivire, evidențiază componenta vinovată.
• View source vs Elements: View source e HTML-ul de pe server, Elements e DOM-ul curent. Diferențele dintre ele (un tbody apărut, un banner inserat) sunt exact cauzele de NG0500.
• Dezactivează JavaScript-ul în DevTools și reîncarcă: vezi exact ce primește utilizatorul înainte de hidratare.
• NG0506: provideStabilityDebugging() listează task-urile care țin aplicația instabilă (cu Zone.js, importă și zone.js/plugins/task-tracking).
• preserveWhitespaces trebuie să aibă aceeași valoare în tsconfig.app.json și tsconfig.server.json; implicitul (false) e varianta recomandată.

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.

Când DA, când NU

Capcane frecvente

• HTML invalid: <div> în <p>, <a> în <a>, tabel fără <tbody>. Validează template-ul; browserul „repară” HTML-ul altfel decât l-a scris serverul.
• Valori diferite pe server și în client (Date.now(), Math.random(), ID-uri generate, fus orar): fără eroare, dar textul se schimbă sub ochii utilizatorului. Transferă valoarea cu TransferState.
• Scripturi terțe (analytics, consent, chat) care modifică DOM-ul înainte de hidratare: încarcă-le după, cu afterNextRender.
• withEventReplay() și withIncrementalHydration() lăsate „pentru siguranță” în v22: primul e redundant, al doilea e deprecated. provideClientHydration() simplu ajunge.
• @placeholder șters pe blocurile cu hydrate, „că oricum nu se vede”: la navigarea client-side se vede.
• Date personale în transfer cache: răspunsurile ajung în HTML. Request-urile cu Authorization/Cookie sunt excluse implicit — nu le include cu includeRequestsWithAuthHeaders fără motiv; folosește filter sau transferCache: false.
• CDN cu minificare HTML care șterge comentariile → NG0507 pe toate paginile.

Fișă rapidă

// ── Config (app.config.ts; ajunge și pe server prin mergeApplicationConfig)
provideClientHydration();                                     // v22: DOM + transfer cache + incremental + replay
provideClientHydration(withNoIncrementalHydration(), withEventReplay());
provideClientHydration(withI18nSupport());
provideClientHydration(withHttpTransferCacheOptions({ filter, includeHeaders, includePostRequests }));
provideClientHydration(withNoHttpTransferCache());
http.get(url, { transferCache: false });                      // opt-out per 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' }   ← ultimă soluție

// ── Erori
// NG0500 nod diferit   NG0501 lipsesc frați   NG0502 lipsește nodul   NG0503 noduri proiectate din afara Angular
// NG0504 ngSkipHydration pe non-componentă    NG0505 lipsesc adnotările (provider lipsă pe server)
// NG0506 aplicația nu devine stabilă în 10 s  NG0507 HTML modificat după server (comentarii șterse)
// NG0508 hydrate triggers fără hidratare incrementală activă