6 - Angular SSR and Incremental Hydration

# New project with SSR enabled
ng new my-ssr-app --ssr

# Add SSR to an existing project
ng add @angular/ssr

# The command automatically generates:
# - server.ts (Express server)
# - src/app/app.config.server.ts (server configuration)
# - Updates angular.json with "server" target
    

// app.config.ts
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideClientHydration } from '@angular/platform-browser';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes),

    // Enable non-destructive hydration
    provideClientHydration(),
  ]
};
    

<!-- This section is rendered on the server but hydrated
     only when it enters the user's viewport -->
@defer (hydrate on viewport) {
  <app-product-list [category]="selectedCategory" />
}

<!-- This component is hydrated when the user
     interacts with it (click, focus, hover) -->
@defer (hydrate on interaction) {
  <app-comment-section [postId]="post.id" />
}

<!-- This is hydrated when the browser is idle,
     meaning it has no other tasks to execute -->
@defer (hydrate on idle) {
  <app-sidebar-recommendations />
}

<!-- This is hydrated after a specific timer -->
@defer (hydrate on timer(3s)) {
  <app-analytics-widget />
}

<!-- Never hydrated: remains static HTML forever -->
@defer (hydrate never) {
  <app-static-footer />
}

<!-- Hydrated immediately (equivalent to full hydration) -->
@defer (hydrate on immediate) {
  <app-critical-cta />
}
    

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

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

// src/app/app.config.server.ts
import { mergeApplicationConfig, ApplicationConfig } from '@angular/core';
import { provideServerRendering } from '@angular/platform-server';
import { provideServerRoutesConfig } from '@angular/ssr';
import { appConfig } from './app.config';
import { serverRoutes } from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    // Enable server-side rendering
    provideServerRendering(),

    // Route-level rendering configuration
    provideServerRoutesConfig(serverRoutes),
  ]
};

// Merge client config with server config
export const config = mergeApplicationConfig(appConfig, serverConfig);
    

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

export const serverRoutes: ServerRoute[] = [
  {
    path: '',
    renderMode: RenderMode.Prerender,  // SSG: generated at build time
  },
  {
    path: 'blog',
    renderMode: RenderMode.Prerender,  // Static page
  },
  {
    path: 'blog/:slug',
    renderMode: RenderMode.Server,  // SSR: generated per request
  },
  {
    path: 'dashboard',
    renderMode: RenderMode.Client,  // CSR: client-side only
  },
  {
    path: '**',
    renderMode: RenderMode.Server,  // Default: SSR for everything else
  },
];
    

// server.ts
import { APP_BASE_HREF } from '@angular/common';
import { CommonEngine } from '@angular/ssr/node';
import express from 'express';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import bootstrap from './src/main.server';

export function app(): express.Express {
  const server = express();
  const serverDistFolder = dirname(fileURLToPath(import.meta.url));
  const browserDistFolder = resolve(serverDistFolder, '../browser');
  const indexHtml = join(serverDistFolder, 'index.server.html');

  const commonEngine = new CommonEngine();

  // Serve static files from the browser folder
  server.get('*.*', express.static(browserDistFolder, {
    maxAge: '1y',   // Aggressive caching for static assets
    index: false,
  }));

  // All other routes go through Angular SSR
  server.get('**', (req, res, next) => {
    const { protocol, originalUrl, baseUrl, headers } = req;

    commonEngine
      .render({
        bootstrap,
        documentFilePath: indexHtml,
        url: `${protocol}://${headers.host}${originalUrl}`,
        publicPath: browserDistFolder,
        providers: [
          { provide: APP_BASE_HREF, useValue: baseUrl }
        ],
      })
      .then(html => res.send(html))
      .catch(err => next(err));
  });

  return server;
}

function run(): void {
  const port = process.env['PORT'] || 4000;
  const server = app();

  server.listen(port, () => {
    console.log(`SSR server listening on http://localhost:${port}`);
  });
}

run();
    

// app.config.ts
import {
  provideClientHydration,
  withEventReplay,
  withIncrementalHydration
} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [
    provideClientHydration(
      // Event Replay: capture events during hydration
      withEventReplay(),
      // Incremental Hydration: hydrate on demand
      withIncrementalHydration(),
    ),
  ]
};
    

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

export const serverRoutes: ServerRoute[] = [
  // Static pages: generated at build time
  {
    path: '',
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'about',
    renderMode: RenderMode.Prerender,
  },

  // Parametric routes: explicit list of paths
  {
    path: 'blog/:slug',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      // Returns an array of objects with parameters
      return [
        { slug: 'angular-ssr-hydration' },
        { slug: 'angular-signals-guide' },
        { slug: 'zoneless-change-detection' },
      ];
    },
  },

  // Dynamic routes: SSR at runtime
  {
    path: 'product/:id',
    renderMode: RenderMode.Server,
  },

  // Dashboard: client-side only
  {
    path: 'admin/**',
    renderMode: RenderMode.Client,
  },
];
    

// seo.service.ts
import { Injectable, inject } from '@angular/core';
import { Meta, Title } from '@angular/platform-browser';
import { DOCUMENT } from '@angular/common';

@Injectable({ providedIn: 'root' })
export class SeoService {
  private title = inject(Title);
  private meta = inject(Meta);
  private document = inject(DOCUMENT);

  updatePageMeta(config: {
    title: string;
    description: string;
    url: string;
    image?: string;
    type?: string;
  }): void {
    // Title tag
    this.title.setTitle(config.title);

    // Meta description
    this.meta.updateTag({
      name: 'description',
      content: config.description
    });

    // Open Graph tags
    this.meta.updateTag({ property: 'og:title', content: config.title });
    this.meta.updateTag({ property: 'og:description', content: config.description });
    this.meta.updateTag({ property: 'og:url', content: config.url });
    this.meta.updateTag({ property: 'og:type', content: config.type || 'website' });

    if (config.image) {
      this.meta.updateTag({ property: 'og:image', content: config.image });
    }

    // Twitter Card
    this.meta.updateTag({ name: 'twitter:card', content: 'summary_large_image' });
    this.meta.updateTag({ name: 'twitter:title', content: config.title });
    this.meta.updateTag({ name: 'twitter:description', content: config.description });

    // Canonical URL
    this.setCanonicalUrl(config.url);
  }

  addStructuredData(data: object): void {
    const script = this.document.createElement('script');
    script.type = 'application/ld+json';
    script.textContent = JSON.stringify(data);
    this.document.head.appendChild(script);
  }

  private setCanonicalUrl(url: string): void {
    let link: HTMLLinkElement | null =
      this.document.querySelector('link[rel="canonical"]');
    if (!link) {
      link = this.document.createElement('link');
      link.setAttribute('rel', 'canonical');
      this.document.head.appendChild(link);
    }
    link.setAttribute('href', url);
  }
}
    

// In a blog article component
@Component({ /* ... */ })
export class ArticlePageComponent {
  private seo = inject(SeoService);

  ngOnInit(): void {
    const article = this.articleData();

    this.seo.updatePageMeta({
      title: `${article.title} | Federico Calo`,
      description: article.summary,
      url: `https://federicocalo.dev/blog/${article.slug}`,
      image: 'https://federicocalo.dev/assets/og-image.jpg',
      type: 'article',
    });

    // Structured Data for Google
    this.seo.addStructuredData({
      '@context': 'https://schema.org',
      '@type': 'Article',
      headline: article.title,
      description: article.summary,
      author: {
        '@type': 'Person',
        name: 'Federico Calo',
        url: 'https://federicocalo.dev',
      },
      datePublished: article.date,
      image: 'https://federicocalo.dev/assets/og-image.jpg',
      publisher: {
        '@type': 'Organization',
        name: 'Federico Calo Dev',
        url: 'https://federicocalo.dev',
      },
    });
  }
}
    

import { Component, inject, PLATFORM_ID } from '@angular/core';
import { isPlatformBrowser, isPlatformServer } from '@angular/common';

@Component({
  selector: 'app-analytics',
  standalone: true,
  template: `<div #trackingContainer></div>`
})
export class AnalyticsComponent {
  private platformId = inject(PLATFORM_ID);

  ngOnInit(): void {
    if (isPlatformBrowser(this.platformId)) {
      // Safe: executed only in the browser
      this.initGoogleAnalytics();
      this.trackPageView();
    }

    if (isPlatformServer(this.platformId)) {
      // Executed only on the server
      console.log('Server-side rendering for:', this.route);
    }
  }

  private initGoogleAnalytics(): void {
    // Safe access to window and document
    const gtag = (window as any).gtag;
    if (gtag) {
      gtag('config', 'G-XXXXXXXXXX');
    }
  }

  private trackPageView(): void {
    // localStorage only available in the browser
    const views = localStorage.getItem('pageViews') || '0';
    localStorage.setItem('pageViews', String(Number(views) + 1));
  }
}
    

import {
  Injectable, inject, PLATFORM_ID,
  TransferState, makeStateKey
} from '@angular/core';
import { isPlatformServer } from '@angular/common';
import { HttpClient } from '@angular/common/http';
import { Observable, of } from 'rxjs';
import { tap } from 'rxjs/operators';

interface Product {
  id: number;
  name: string;
  price: number;
}

const PRODUCTS_KEY = makeStateKey<Product[]>('products');

@Injectable({ providedIn: 'root' })
export class ProductService {
  private http = inject(HttpClient);
  private transferState = inject(TransferState);
  private platformId = inject(PLATFORM_ID);

  getProducts(): Observable<Product[]> {
    // 1. Check if data is already in TransferState
    const cached = this.transferState.get(PRODUCTS_KEY, null);
    if (cached) {
      // Data transferred from server: use it and remove it
      this.transferState.remove(PRODUCTS_KEY);
      return of(cached);
    }

    // 2. No cached data: make the HTTP request
    return this.http.get<Product[]>('/api/products').pipe(
      tap(products => {
        if (isPlatformServer(this.platformId)) {
          // 3. On server: save to TransferState
          this.transferState.set(PRODUCTS_KEY, products);
        }
      })
    );
  }
}
    

import { Component, afterNextRender, afterRender, ElementRef, viewChild } from '@angular/core';

@Component({
  selector: 'app-chart',
  standalone: true,
  template: `<canvas #chartCanvas width="800" height="400"></canvas>`
})
export class ChartComponent {
  canvas = viewChild.required<ElementRef<HTMLCanvasElement>>('chartCanvas');

  constructor() {
    // Executed ONCE after the first render in the browser
    // NOT executed on the server
    afterNextRender(() => {
      const ctx = this.canvas().nativeElement.getContext('2d');
      this.initChart(ctx!);
    });

    // Executed EVERY TIME Angular renders the component
    // Useful for syncing with external DOM libraries
    afterRender(() => {
      this.updateChartDimensions();
    });
  }

  private initChart(ctx: CanvasRenderingContext2D): void {
    // Initialize a chart with Canvas API
    // Safe: executed only in the browser
  }

  private updateChartDimensions(): void {
    // Update dimensions based on viewport
  }
}
    

<!-- Product page layout optimized for Core Web Vitals -->

<!-- CRITICAL: immediate hydration (above-the-fold) -->
<app-navbar />
<app-product-hero [product]="product()" />

<!-- VISIBILITY: hydrate on viewport -->
@defer (hydrate on viewport) {
  <app-product-details [product]="product()" />
}

@defer (hydrate on viewport) {
  <app-product-reviews [productId]="product().id" />
}

<!-- INTERACTION: hydrate on user input -->
@defer (hydrate on interaction) {
  <app-add-to-cart [product]="product()" />
}

<!-- BACKGROUND: hydrate when browser is free -->
@defer (hydrate on idle) {
  <app-related-products [categoryId]="product().categoryId" />
}

<!-- DEFERRED: hydrate after timer -->
@defer (hydrate on timer(5s)) {
  <app-user-tracking [productId]="product().id" />
}

<!-- STATIC: never hydrated -->
@defer (hydrate never) {
  <app-footer />
}
    

// performance-monitor.service.ts
import { Injectable, inject, PLATFORM_ID, afterNextRender } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';

@Injectable({ providedIn: 'root' })
export class PerformanceMonitorService {
  private platformId = inject(PLATFORM_ID);

  constructor() {
    afterNextRender(() => {
      this.observeWebVitals();
    });
  }

  private observeWebVitals(): void {
    if (!isPlatformBrowser(this.platformId)) return;

    // Largest Contentful Paint
    const lcpObserver = new PerformanceObserver((list) => {
      const entries = list.getEntries();
      const lastEntry = entries[entries.length - 1];
      console.log('LCP:', lastEntry.startTime, 'ms');
    });
    lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });

    // First Input Delay
    const fidObserver = new PerformanceObserver((list) => {
      const entries = list.getEntries() as PerformanceEventTiming[];
      entries.forEach(entry => {
        console.log('FID:', entry.processingStart - entry.startTime, 'ms');
      });
    });
    fidObserver.observe({ type: 'first-input', buffered: true });

    // Cumulative Layout Shift
    const clsObserver = new PerformanceObserver((list) => {
      let clsScore = 0;
      list.getEntries().forEach((entry: any) => {
        if (!entry.hadRecentInput) {
          clsScore += entry.value;
        }
      });
      console.log('CLS:', clsScore);
    });
    clsObserver.observe({ type: 'layout-shift', buffered: true });
  }
}