GeezerVison

What is hydration

Hydration is the process that restores the server-side rendered application on the client. This includes things like reusing the server rendered DOM structures, persisting the application state, transferring application data that was retrieved already by the server, and other processes.

Why is hydration important?

Hydration improves application performance by avoiding extra work to re-create DOM nodes. Instead, Angular tries to match existing DOM elements to the application's structure at runtime and reuses DOM nodes when possible. This results in a performance improvement that can be measured using Core Web Vitals (CWV) statistics, such as reducing the First Input Delay (FID) and Largest Contentful Paint (LCP), as well as Cumulative Layout Shift (CLS). Improving these numbers also affects things like SEO performance.

Without hydration enabled, server-side rendered Angular applications will destroy and re-render the application's DOM, which may result in a visible UI flicker. This re-rendering can negatively impact Core Web Vitals like LCP and cause a layout shift. Enabling hydration allows the existing DOM to be re-used and prevents a flicker.

How do you enable hydration in Angular

Hydration can be enabled for server-side rendered (SSR) applications only. Follow the Angular SSR Guide to enable server-side rendering first.

Using Angular CLI

If you've used Angular CLI to enable SSR (either by enabling it during application creation or later via ng add @angular/ssr), the code that enables hydration should already be included into your application.

Manual setup

If you have a custom setup and didn't use Angular CLI to enable SSR, you can enable hydration manually by visiting your main application component or module and importing provideClientHydration from @angular/platform-browser. You'll then add that provider to your app's bootstrapping providers list.

import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration()]
});

Alternatively if you are using NgModules, you would add provideClientHydration to your root app module's provider list.

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

@NgModule({
  declarations: [App],
  exports: [App],
  bootstrap: [App],
  providers: [provideClientHydration()],
})
export class AppModule {}

Verify that hydration is enabled

After you've configured hydration and have started up your server, load your application in the browser.

While running an application in dev mode, you can confirm hydration is enabled by opening the Developer Tools in your browser and viewing the console. You should see a message that includes hydration-related stats, such as the number of components and nodes hydrated. Angular calculates the stats based on all components rendered on a page, including those that come from third-party libraries.

You can also use Angular DevTools browser extension to see hydration status of components on a page. Angular DevTools also allows to enable an overlay to indicate which parts of the page were hydrated. If there is a hydration mismatch error - DevTools would also highlight a component that caused the error.

Capturing and replaying events

When an application is rendered on the server, it is visible in a browser as soon as produced HTML loads. Users may assume that they can interact with the page, but event listeners are not attached until hydration completes. The Event Replay feature captures all events that happen before hydration and replays those events once hydration has completed.

Event replay is enabled alongside incremental hydration. If you opt out of incremental hydration with withNoIncrementalHydration(), you can still enable event replay using the withEventReplay() function:

import {
  provideClientHydration,
  withEventReplay,
  withNoIncrementalHydration,
  bootstrapApplication,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration(), withEventReplay())],
});

How event replay works

Event Replay is a feature that improves user experience by capturing user events that were triggered before the hydration process is complete. Then those events are replayed, ensuring none of that interaction was lost.

The Event Replay is divided into three main phases:

• Capturing user interactions
  Prior to Hydration, Event Replay captures and stores all interactions that the user may perform, such as clicks and other browser native events.

• Storing events
  The Event Contract keeps in memory all the interactions recorded in the previous step, ensuring that they are not lost for later replay.

• Relaunch of events
  Once Hydration is complete, Angular re-invokes the captured events.

Event replay supports native browser events, for example click, mouseover, and focusin. If you'd like to learn more about JSAction, the library that powers event replay, you can read more on the readme.

This feature ensures a consistent user experience, preventing user actions performed before hydration from being ignored.

Constraints

Hydration imposes a few constraints on your application that are not present without hydration enabled. Your application must have the same generated DOM structure on both the server and the client. The process of hydration expects the DOM tree to have the same structure in both places. This also includes whitespaces and comment nodes that Angular produces during the rendering on the server. Those whitespaces and nodes must be present in the HTML generated by the server-side rendering process.

If there is a mismatch between server and client DOM tree structures, the hydration process will encounter problems attempting to match up what was expected to what is actually present in the DOM. Components that do direct DOM manipulation using native DOM APIs are the most common culprit.

Direct DOM Manipulation

If you have components that manipulate the DOM using native DOM APIs or use innerHTML or outerHTML, the hydration process will encounter errors. Specific cases where DOM manipulation is a problem are situations like accessing the document, querying for specific elements, and injecting additional nodes using appendChild. Detaching DOM nodes and moving them to other locations will also result in errors.

This is because Angular is unaware of these DOM changes and cannot resolve them during the hydration process. Angular will expect a certain structure, but it will encounter a different structure when attempting to hydrate. This mismatch will result in hydration failure and throw a DOM mismatch error (see below).

It is best to refactor your component to avoid this sort of DOM manipulation. Try to use Angular APIs to do this work, if you can. If you cannot refactor this behavior, use the ngSkipHydration attribute (described below) until you can refactor into a hydration friendly solution.

Valid HTML structure

There are a few cases where if you have a component template that does not have valid HTML structure, this could result in a DOM mismatch error during hydration.

As an example, here are some of the most common cases of this issue.

• <table> without a <tbody>
• <div> inside a <p>
• <a> inside another <a>

If you are uncertain about whether your HTML is valid, you can use a syntax validator to check it.

Preserve Whitespaces Configuration

When using the hydration feature, we recommend using the default setting of false for preserveWhitespaces. If this setting is not in your tsconfig, the value will be false and no changes are required. If you choose to enable preserving whitespaces by adding preserveWhitespaces: true to your tsconfig, it is possible you may encounter issues with hydration. This is not yet a fully supported configuration.

If you choose to set this setting in your tsconfig, we recommend to set it only in tsconfig.app.json which by default the tsconfig.server.json will inherit it from.

Custom or Noop Zone.js are not yet supported

Hydration relies on a signal from Zone.js when it becomes stable inside an application, so that Angular can start the serialization process on the server or post-hydration cleanup on the client to remove DOM nodes that remained unclaimed.

Providing a custom or a "noop" Zone.js implementation may lead to a different timing of the "stable" event, thus triggering the serialization or the cleanup too early or too late. This is not yet a fully supported configuration and you may need to adjust the timing of the onStable event in the custom Zone.js implementation.

Errors

There are several hydration related errors you may encounter ranging from node mismatches to cases when the ngSkipHydration was used on an invalid host node. The most common error case that may occur is due to direct DOM manipulation using native APIs that results in hydration being unable to find or match the expected DOM tree structure on the client that was rendered by the server. The other case where you may encounter this type of error was mentioned in the Valid HTML structure section earlier. So, make sure the HTML in your templates is using valid structure, and you'll avoid that error case.

For a full reference on hydration related errors, visit the Errors Reference Guide.

How to skip hydration for particular components

Some components may not work properly with hydration enabled due to some of the aforementioned issues, like Direct DOM Manipulation. As a workaround, you can add the ngSkipHydration attribute to a component's tag in order to skip hydrating the entire component.

<app-example ngSkipHydration />

Alternatively you can set ngSkipHydration as a host binding.

@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}

The ngSkipHydration attribute will force Angular to skip hydrating the entire component and its children. Using this attribute means that the component will behave as if hydration is not enabled, meaning it will destroy and re-render itself.

The ngSkipHydration attribute can only be used on component host nodes. Angular throws an error if this attribute is added to other nodes.

Keep in mind that adding the ngSkipHydration attribute to your root application component would effectively disable hydration for your entire application. Be careful and thoughtful about using this attribute. It is intended as a last resort workaround. Components that break hydration should be considered bugs that need to be fixed.

Hydration Timing and Application Stability

Application stability is an important part of the hydration process. Hydration and any post-hydration processes only occur once the application has reported stability. There are a number of ways that stability can be delayed. Examples include setting timeouts and intervals, unresolved promises, and pending microtasks. In those cases, you may encounter the Application remains unstable error, which indicates that your app has not yet reached the stable state after 10 seconds. If you're finding that your application is not hydrating right away, take a look at what is impacting application stability and refactor to avoid causing these delays.

Debugging Application Stability

The provideStabilityDebugging utility helps identify why your application fails to stabilize. This utility is provided by default in dev mode when using provideClientHydration. You can also add it manually to the application providers for use in production bundles or when using SSR without hydration, for example. The feature logs information to the console if the application takes longer than expected to stabilize.

import {provideStabilityDebugging} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import 'zone.js/plugins/task-tracking'; // Use if you have Zone.js with `provideZoneChangeDetection`

bootstrapApplication(App, {
  providers: [provideStabilityDebugging()],
});

When enabled, the utility logs pending tasks (PendingTasks) to the console. If your application uses Zone.js, you can also import zone.js/plugins/task-tracking to see which macrotasks are keeping the Angular Zone from stabilizing. This plugin provides the stack trace of the macrotask creation, effectively helping you identify the source of the delay.

I18N

To enable hydration for i18n blocks, you can add withI18nSupport to your provideClientHydration call.

import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration(withI18nSupport())]
});

Consistent rendering across server-side and client-side

Avoid introducing @if blocks and other conditionals that display different content when server-side rendering than client-side rendering, such as using an @if block with Angular's isPlatformBrowser function. These rendering differences cause layout shifts, negatively impacting end-user experience and core web vitals.

Third Party Libraries with DOM Manipulation

There are a number of third party libraries that depend on DOM manipulation to be able to render. D3 charts is a prime example. These libraries worked without hydration, but they may cause DOM mismatch errors when hydration is enabled. For now, if you encounter DOM mismatch errors using one of these libraries, you can add the ngSkipHydration attribute to the component that renders using that library.

Third Party Scripts with DOM Manipulation

Many third party scripts, such as ad trackers and analytics, modify the DOM before hydration can occur. These scripts may cause hydration errors because the page no longer matches the structure expected by Angular. Prefer deferring this type of script until after hydration whenever possible. Consider using AfterNextRender to delay the script until post-hydration processes have occurred.

CDNs and browser extensions

Code outside your application can change the HTML from the server before hydration starts. You often can't see these errors on your computer, because they don't happen on your local server.

CDNs that change HTML. Some CDN features change HTML on its way to the browser. For example, some features remove comment nodes and whitespace, but hydration needs them. Another example is Email Address Obfuscation from Cloudflare, which is on by default. This feature changes email addresses to elements like <span class="__cf_email__" data-cfemail="...">. It also changes mailto: links and adds a script that changes the content back. If this script doesn't run before hydration starts, Angular finds an element where it expects text. Your local server doesn't use the CDN, so your application works on your computer and fails only in production.

Browser extensions. Some browser extensions change the page before hydration starts. Examples are click-to-call tools, translators, and password managers. You can't control these extensions. Only users who install them have the problem, so you may see errors from only some users.

To fix these errors:

• Add ngSkipHydration to the component host around the changed content. Add it in the template where you write that content, like this: <app-contact ngSkipHydration><a href="tel:...">...</a></app-contact>. Angular then renders this content again in the browser, and this removes the changes. You can use this attribute only on component host elements, so you can't add it to the <a> element. Read more in how to skip hydration.
• Turn off the CDN feature for your application. In Cloudflare, turn off Email Address Obfuscation in the security settings, or use a Configuration Rule to turn it off for the hostnames of your application.

Incremental Hydration

Incremental hydration is an advanced form of hydration that allows for more granular control over when hydration happens. See the incremental hydration guide for more information.