🚀 Angular SSR and Incremental Hydration: Faster Apps, Better Core Web Vitals

🤔 The performance problem SSR was supposed to solve

When you ship a standard Angular app, the browser receives a mostly empty HTML shell — just a <app-root></app-root> tag and a big JavaScript bundle. The user stares at a blank screen until that bundle downloads, parses, and executes. Only then do they see anything. 😩

That's bad for users and worse for Google. Core Web Vitals — the metrics that Google uses to score your page speed and factor into SEO rankings — care deeply about how quickly users see content and can interact with it.

Server-Side Rendering (SSR) was the first fix: render the full HTML on the server, send it to the browser immediately, and let the user see real content before any JavaScript loads. But SSR introduced a new problem: the hydration gap. 😰

The server sends you a beautiful, rendered page. Then Angular's JavaScript arrives, tears down that DOM, and re-renders everything from scratch. For a brief moment, the page flickers. Layout shifts happen. Users click on buttons that don't respond yet because the JavaScript isn't ready. That's a terrible experience.

Angular solved this in three stages:

Version	Milestone
Angular 16	Full-application hydration (developer preview)
Angular 17	Full hydration stable ✅ · `@defer` blocks introduced
Angular 18	Event replay — captures clicks before hydration completes
Angular 19	Incremental hydration (developer preview)
Angular 20	Incremental hydration + route-level render modes stable ✅ 🎉

🧠 Understanding the three concepts

Before diving into code, let's make sure the terminology is clear.

🖥️ SSR (Server-Side Rendering)

The server renders your Angular app to full HTML and sends it to the browser. The user sees meaningful content instantly — no blank screen. But the page is static until Angular's JavaScript loads and "wakes it up."

💧 Hydration

The process of Angular taking over a server-rendered DOM without destroying it. Instead of rebuilding every DOM node from scratch, Angular walks the existing HTML, matches it to the component tree, and attaches event listeners in place. Without hydration, Angular would destroy and re-render the application's DOM, resulting in a visible UI flicker that negatively impacts Core Web Vitals like LCP and causes layout shifts.

⚡ Incremental Hydration

Incremental hydration is a performance improvement that builds on top of full application hydration. It can produce smaller initial bundles while still providing an end-user experience comparable to full application hydration. Smaller bundles improve initial load times, reducing First Input Delay (FID) and Cumulative Layout Shift (CLS).

In plain terms: instead of hydrating your entire app at once when JavaScript loads, you hydrate individual components on demand — when they scroll into view, when the user interacts with them, or when the browser is idle. The rest of the page stays as fast, static HTML until it's needed. 🎯

📊 Why this matters: Core Web Vitals explained

Google scores your page on three key metrics. Here's how Angular's SSR stack improves each one:

🎨 LCP — Largest Contentful Paint

How quickly does the largest visible element appear?

Without SSR, LCP is slow because the browser waits for JavaScript before rendering anything. With SSR + hydration, the server sends fully-rendered HTML — so the hero image or headline appears immediately, giving you a fast LCP.

⚡ FID / INP — First Input Delay / Interaction to Next Paint

How quickly does the page respond to user interaction?

This is where incremental hydration shines. By deferring hydration to critical moments, Angular apps load faster, respond more quickly to user actions, and minimize visual shifts from unnecessary DOM reflows. A component that's still dehydrated doesn't block the main thread — so the rest of the page stays responsive.

📐 CLS — Cumulative Layout Shift

Do elements jump around as the page loads?

Incremental hydration also lets you use deferrable views for content that may not have been deferrable before — specifically, you can now use deferrable views for content above the fold. Prior to incremental hydration, putting a @defer block above the fold would result in placeholder content rendering and then being replaced by the main template, causing a layout shift. Incremental hydration means the main template renders with no layout shift on hydration. 🙌

🔍 SEO bonus

Search engines index the server-rendered HTML before any JavaScript runs. With SSR, your content is fully crawlable — dynamic Angular apps become as SEO-friendly as static sites.

🛠️ Part 1: Setting up SSR

New project with SSR

The easiest way — pass the --ssr flag when creating a new project:

ng new my-app --ssr

This generates everything you need: main.server.ts, server.ts (an Express server), and the correct app.config.ts with hydration pre-configured. ✅

Adding SSR to an existing project

ng add @angular/ssr

The schematic creates the server files and updates your angular.json automatically. Once done, your project structure gains:

src/
  app/
    app.config.ts         ← application providers (hydration lives here)
    app.config.server.ts  ← server-specific providers
  main.ts                 ← client bootstrap
  main.server.ts          ← server bootstrap
server.ts                 ← Express + Angular SSR engine

The generated `app.config.ts`

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

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideClientHydration(), // 💧 full-app hydration enabled
  ],
};

At this point you have SSR + full hydration. The page renders on the server, Angular takes over on the client without destroying the DOM, and there's no flicker. Good — but we can do better. 🚀

🏗️ Part 2: Enabling incremental hydration

Enable incremental hydration by adding the withIncrementalHydration() function to the provideClientHydration provider.

import {
  ApplicationConfig,
} from '@angular/core';
import {
  provideClientHydration,
  withIncrementalHydration,
} from '@angular/platform-browser';
import { provideRouter } from '@angular/router';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideClientHydration(
      withIncrementalHydration() // ⚡ incremental hydration enabled
    ),
  ],
};

💡 Incremental hydration automatically enables event replay under the hood. If you already have withEventReplay() in your provider list, you can safely remove it after enabling incremental hydration.

That's the entire setup. One function call. Now you can start marking components for incremental hydration in your templates. 🎉

🎯 Part 3: The `@defer` block with `hydrate` triggers

Incremental hydration is built on top of Angular's @defer primitive — the same syntax you may already use for lazy loading. The key addition is the hydrate trigger.

Adding a hydrate trigger to a defer block tells Angular that it should load that block's dependencies during server-side rendering and render the main template rather than the @placeholder. When client-side rendering, the dependencies are still deferred, and the defer block content stays dehydrated until its hydrate trigger fires.

Here's the basic pattern:

@defer (hydrate on idle) {
  <app-heavy-sidebar />
} @placeholder {
  <div class="sidebar-skeleton">Loading...</div>
}

The server renders <app-heavy-sidebar /> fully — the user sees it immediately. On the client, it stays as static HTML until the browser is idle, at which point Angular hydrates it and makes it interactive. 🙌

🗂️ All hydrate triggers

Angular provides a variety of triggers to control hydration behavior:

`hydrate on idle` — Browser is idle

@defer (hydrate on idle) {
  <app-analytics-widget />
} @placeholder {
  <div class="widget-skeleton"></div>
}

Use for: Non-critical UI elements like sidebars, recommendation panels, supplementary info cards. Hydration waits until the browser has no higher-priority work. 😴

`hydrate on viewport` — Scrolled into view

@defer (hydrate on viewport) {
  <app-comments-section />
} @placeholder {
  <div class="comments-skeleton" style="min-height: 400px"></div>
}

Use for: Comments, footers, below-the-fold sections — anything the user hasn't seen yet. Zero JS cost until they scroll down. 📜

`hydrate on interaction` — User clicks or taps

@defer (hydrate on interaction) {
  <app-date-picker />
} @placeholder {
  <div class="datepicker-placeholder">Select a date</div>
}

Use for: Complex widgets that are visible but rarely used immediately — date pickers, map views, rich text editors. The user sees it, but Angular doesn't pay the JavaScript cost until they actually touch it. 🖱️

`hydrate on hover` — Mouse hovers over it

@defer (hydrate on hover) {
  <app-product-quick-view />
} @placeholder {
  <div class="product-card-static">{{ product.name }}</div>
}

Use for: Hover cards, tooltips, preview panels. A hover is a strong signal the user is about to interact. 🖱️

`hydrate on immediate` — As soon as possible

@defer (hydrate on immediate) {
  <app-main-nav />
} @placeholder {
  <nav class="nav-skeleton"></nav>
}

Use for: Critical interactive elements like navigation or primary call-to-action buttons that need to be ready the moment the page loads. ⚡

`hydrate on timer` — After a delay

@defer (hydrate on timer(3s)) {
  <app-chat-widget />
} @placeholder {
  <div class="chat-bubble">Chat with us</div>
}

Use for: Chat widgets, subscription prompts — things you want to load after the user has had a moment to engage with the page. ⏱️

`hydrate when` — Custom condition

@defer (hydrate when userIsLoggedIn()) {
  <app-user-dashboard />
} @placeholder {
  <div class="login-prompt">Log in to view your dashboard</div>
}

Use for: Content that should only hydrate when a specific application state is true — authenticated sections, feature-flagged components, etc. 🔐

`hydrate never` — Permanently static

@defer (hydrate never) {
  <app-footer-copyright />
}

Use for: Truly static content that never needs JavaScript — legal text, copyright notices, decorative elements. This is effectively a server-only component. 📄

🔀 Combining loading and hydration triggers

The @defer block in an incremental hydration context controls two distinct phases — loading (when to fetch the JavaScript chunk) and hydrating (when to execute the logic and attach listeners to the existing HTML). By combining these triggers, developers can design highly sophisticated performance profiles.

<!-- Load JS in background when idle, but only hydrate when user interacts -->
@defer (on idle; hydrate on interaction) {
  <app-complex-chart [data]="chartData()" />
} @placeholder {
  <div class="chart-shell" style="min-height: 300px">
    <!-- Server-rendered chart image or skeleton here -->
  </div>
}

This pattern is powerful for heavy widgets like charts or maps:

🖥️ Server renders the chart — user sees it immediately (great LCP)
💤 Browser idle — JavaScript for the chart fetches in the background
🖱️ User clicks — Angular hydrates and the chart becomes fully interactive
🎯 Result — Fast LCP, zero Time to Interactive impact until interaction

🏗️ Part 4: Route-level render modes

Angular 20 also stabilised per-route render modes — you can choose between SSR, SSG (pre-rendering), and CSR on a route-by-route basis. This lives in your server routes config:

// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '',            // homepage
    renderMode: RenderMode.Prerender, // 📄 Static — pre-rendered at build time
  },
  {
    path: 'blog/:slug',  // individual blog posts
    renderMode: RenderMode.Prerender, // 📄 Static — great for SEO
  },
  {
    path: 'dashboard',   // user dashboard — personalised, can't pre-render
    renderMode: RenderMode.Server,    // 🖥️ SSR on every request
  },
  {
    path: 'settings',    // user settings — no SEO needed
    renderMode: RenderMode.Client,    // 💻 CSR — skip SSR entirely
  },
];

import { mergeApplicationConfig } from '@angular/core';
import { provideServerRendering, withRoutes } from '@angular/ssr';
import { appConfig } from './app.config';
import { serverRoutes } from './app.routes.server';

const serverConfig = mergeApplicationConfig(appConfig, {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
  ],
});

export default serverConfig;

💡 Don't force every route to use SSR. Use a route-based strategy — pre-render what you can, SSR what must be dynamic, and CSR what doesn't need SEO.

🔄 HTTP Transfer Cache: don't fetch twice

When your app makes HTTP calls in components during SSR, those calls run on the server. Without the transfer cache, the exact same calls would fire again on the client during hydration — wasting bandwidth and adding latency. 😓

Angular's HttpTransferCache solves this automatically. By default, HttpClient caches all HEAD and GET requests during SSR and reuses them during hydration on the client. You can configure this behaviour using withHttpTransferCacheOptions inside provideClientHydration().

import {
  provideClientHydration,
  withIncrementalHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration(
      withIncrementalHydration(),
      withHttpTransferCacheOptions({
        includePostRequests: true, // cache POST requests too if needed
      })
    ),
  ],
};

⚠️ Common pitfalls and how to avoid them

🚫 DOM mismatch errors

The most common issue. Angular requires the same generated DOM structure on both the server and the client, including whitespaces and comment nodes. If the HTML produced by SSR is altered between server and client, the hydration process will encounter problems.

// ❌ This causes hydration mismatches
@if (isPlatformBrowser(this.platformId)) {
  <user-greeting [name]="currentUser" />
}

// ✅ Keep rendered content consistent — use afterNextRender for browser-only logic
constructor() {
  afterNextRender(() => {
    // Browser-only init here — runs after hydration, not during
    this.initBrowserOnlyFeature();
  });
}

Avoid using isPlatformBrowser in templates with @if or other conditionals to render different content on server and client. This causes hydration mismatches and layout shifts, negatively impacting user experience and Core Web Vitals. Instead, use afterNextRender for browser-specific initialization.

🚫 Third-party DOM manipulation libraries

Libraries that depend on DOM manipulation, like D3 charts, may cause DOM mismatch errors when hydration is enabled. 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.

<!-- Opt this component out of hydration entirely -->
<app-d3-chart ngSkipHydration />

🚫 Empty `@placeholder` causing layout shifts

Always give your @placeholder a minimum height matching the deferred content. A dimensionless placeholder causes a layout shift when the real content loads, directly hurting your CLS score. 📐

<!-- ❌ Empty placeholder — causes layout shift -->
@defer (hydrate on viewport) {
  <app-comments />
} @placeholder {
  <div></div>
}

<!-- ✅ Sized placeholder — no layout shift -->
@defer (hydrate on viewport) {
  <app-comments />
} @placeholder {
  <div class="comments-skeleton" style="min-height: 400px">
    Loading comments...
  </div>
}

🚫 Server-only providers leaking to the client

Use app.config.server.ts for providers that should only exist on the server (like mock APIs or server-side auth). Never put server-specific logic in app.config.ts — that file runs on both platforms.

📋 Setup checklist

🖥️ Add SSR: ng add @angular/ssr or ng new my-app --ssr
💧 Confirm provideClientHydration() is in app.config.ts
⚡ Add withIncrementalHydration() to provideClientHydration()
🗂️ Create app.routes.server.ts and set per-route render modes
💾 Confirm HttpTransferCache is active (it's on by default with provideClientHydration)
🎯 Wrap heavy components in @defer blocks with appropriate hydrate triggers
📐 Give all @placeholder blocks a meaningful minimum height
🚫 Remove any isPlatformBrowser checks from templates
🔍 Add ngSkipHydration to any third-party DOM manipulation components
🏃 Run Lighthouse before and after to measure your CWV improvements

🎯 Quick decision guide: which trigger to use?

Component type	Recommended trigger
Navigation / primary CTA	`hydrate on immediate`
Hero section content	SSR only (no defer needed)
Above-the-fold widgets	`hydrate on idle`
Below-the-fold sections	`hydrate on viewport`
Complex interactive widgets	`hydrate on interaction`
Hover cards / previews	`hydrate on hover`
Chat / subscription prompts	`hydrate on timer(3s)`
Auth-gated content	`hydrate when condition()`
Purely decorative / legal text	`hydrate never`

🎉 Wrapping up

Angular's SSR story has matured dramatically. What started as a rough "render on server, destroy and re-render on client" approach in Angular Universal is now a sophisticated, granular, trigger-based hydration system that gives you real control over your Core Web Vitals.

The power of incremental hydration is in that combination: the server renders the component so the user sees full content immediately, then Angular fetches the JavaScript in the background on idle, and only hydrates when the user actually interacts — resulting in fast LCP and zero Time to Blocking impact.

If your Angular app doesn't use SSR yet, ng add @angular/ssr is the fastest performance win you can make today. If you're already on SSR, adding withIncrementalHydration() and wrapping your heavy components in @defer (hydrate on ...) blocks is the next step. Your Lighthouse scores — and your users — will thank you. 🚀

📚 Further reading

🖥️ Angular docs: Server-side rendering guide
💧 Angular docs: Hydration guide
⚡ Angular docs: Incremental hydration guide
🗂️ Angular docs: Route-level render modes
📊 Google: Core Web Vitals
🔗 Part 3 of this series: Zoneless Angular

Command Palette

Comments

More from this blog