SSR, Prerendering et modes de rendu

Par défaut, Angular livre l’application en CSR (client-side rendering) : le serveur envoie un <app-root></app-root> vide, et le navigateur doit télécharger, analyser et exécuter tout le JavaScript — puis aussi récupérer les données — avant d’afficher quoi que ce soit d’utile. Le SSR (rendu sur le serveur, à chaque requête) et le SSG (prerender, au moment du build) déplacent le premier rendu ailleurs : l’utilisateur reçoit tout de suite du HTML avec du contenu.

Avec @angular/ssr, vous ne choisissez pas une fois pour toute l’application, mais par route : le fichier app.routes.server.ts indique pour chaque chemin s’il est en RenderMode.Prerender, RenderMode.Server ou RenderMode.Client. C’est ce qu’on appelle le hybrid rendering. L’API des routes serveur est apparue en v19 et est stable depuis la v20.

Trois modes de rendu

Ce que fait concrètement le serveur en mode Server : pour chaque requête, @angular/ssr crée une nouvelle plateforme, appelle la fonction de bootstrap de main.server.ts, laisse le routeur naviguer vers l’URL, attend que l’application devienne stable (toutes les requêtes HTTP et les PendingTasks terminées), sérialise le DOM en HTML et détruit l’application. La conséquence pratique : le TTFB d’une page SSR est au moins aussi long que celui de l’API la plus lente appelée pendant le rendu.

Dans une vraie application hybride, les modes coexistent : la page d’accueil et les pages marketing sont prérendues, la recherche est rendue sur le serveur, et l’espace compte s’exécute uniquement dans le navigateur.

Ce qui se passe lors d’une requête

Cinq moments comptent, dans l’ordre où l’utilisateur les vit :

• TTFB (time to first byte) — le premier octet de la réponse HTML.
• FCP (first contentful paint) — le premier texte ou la première image à l’écran.
• LCP (largest contentful paint) — l’élément principal apparaît (le titre, l’image du produit). C’est la métrique que l’utilisateur ressent comme « c’est chargé ».
• Hydration — le JS est arrivé, Angular reprend le HTML existant et attache les listeners.
• Interactif — un clic fait vraiment quelque chose. À partir de ce moment, l’INP compte (la rapidité de réaction de la page).

Avec le SSR et le SSG, entre le LCP et l’état « interactif », il y a une fenêtre pendant laquelle la page semble prête, mais où les boutons n’ont pas encore de listener. Sur un téléphone modeste, avec un bundle de quelques centaines de KB, cette fenêtre dure facilement 1 à 3 secondes. Lancez la simulation et comparez les trois modes sur le même réseau.

Remarquez ce qui ne change pas : main.js a la même taille dans les trois modes. Le SSR ne réduit pas le JavaScript, donc l’interactivité arrive à peu près au même moment qu’en CSR — parfois même un peu plus tard, car le HTML est plus gros et l’hydration consomme aussi du CPU. Le vrai gain, c’est le LCP. Pour réduire la fenêtre non interactive : moins de JS initial (routes lazy, @defer), l’incremental hydration et l’event replay, qui ne perd pas les clics faits pendant cette fenêtre.

Ce que voit un crawler

Un crawler part du HTML qu’il reçoit (ce que vous voyez avec Afficher le code source, pas dans l’onglet Éléments). En CSR, ce HTML est identique pour n’importe quelle URL. Googlebot peut exécuter du JavaScript, mais plus tard et avec des limites ; les bots qui génèrent des aperçus dans les chats et les réseaux sociaux ne lisent généralement que le HTML initial. Il y a un détail souvent ignoré : le code de statut. Un serveur statique ne sait pas que /produse/9999 n’existe pas, il répond donc 200 — un « soft 404 ».

HTTP/1.1 200 OK<!doctype html><html lang="fr"><head>  <title>Boutique</title>  <link rel="stylesheet" href="styles-5INURTSO.css"></head><body>  <app-root></app-root>  <script src="main-HG7KQWZB.js" type="module"></script></body></html>

Le titre et les balises meta se définissent avec les services Title et Meta de @angular/platform-browser. Ils passent par DOCUMENT, donc ils fonctionnent aussi sur le serveur : tout ce que vous définissez pendant le rendu se retrouve dans le HTML envoyé. Pour les pages sans données, la propriété title de la route suffit (ou votre propre TitleStrategy, si vous voulez un format commun).

import { Component, computed, effect, inject, input } from '@angular/core';
import { httpResource } from '@angular/common/http';
import { Meta, Title } from '@angular/platform-browser';

interface Product { id: string; name: string; description: string; imageUrl: string }

@Component({
  selector: 'app-product-page',
  template: `
    @if (product.hasValue()) {
      <h1>{{ product.value().name }}</h1>
      <p>{{ product.value().description }}</p>
    }
  `,
})
export default class ProductPage {
  readonly id = input.required<string>(); // issu de la route produse/:id (withComponentInputBinding)

  private readonly title = inject(Title);
  private readonly meta = inject(Meta);
  protected readonly product = httpResource<Product>(() => `/api/products/${this.id()}`);

  constructor() {
    // S’exécute aussi sur le serveur : les balises se retrouvent dans le HTML envoyé aux crawlers.
    effect(() => {
      if (!this.product.hasValue()) return;
      const p = this.product.value();
      this.title.setTitle(`${p.name} — Boutique`);
      this.meta.updateTag({ name: 'description', content: p.description });
      this.meta.updateTag({ property: 'og:title', content: p.name });
      this.meta.updateTag({ property: 'og:description', content: p.description });
      this.meta.updateTag({ property: 'og:image', content: p.imageUrl });
    });
  }
}

Mise en place : ce que génère ng add

# nouveau projet, avec SSR + prerender configurés dès le départ
ng new magazin --ssr

# projet existant : ajoute @angular/ssr, express et les fichiers serveur
ng add @angular/ssr

# build de production → dist/magazin/browser + dist/magazin/server
ng build

# démarre le serveur Node (script ajouté par ng add dans package.json)
npm run serve:ssr:magazin        # = node dist/magazin/server/server.mjs

La commande ajoute les dépendances (@angular/ssr, express), quatre fichiers et quelques options dans angular.json. Il vaut la peine de savoir ce que fait chacun, car vous allez les modifier :

• server.ts — le serveur Express. Il sert les fichiers statiques de dist/…/browser et confie le reste des requêtes à AngularNodeAppEngine.handle(), qui renvoie une Response (ou null si l’URL n’est pas une route Angular). L’export reqHandler est utilisé par la CLI : ng serve effectue aussi le rendu sur le serveur.
• main.server.ts — la fonction de bootstrap que le serveur appelle à chaque rendu.
• app.config.server.ts — provideServerRendering(withRoutes(serverRoutes)), combiné à la config du navigateur via mergeApplicationConfig.
• app.routes.server.ts — le render mode par route. Par défaut, tout est en Prerender.
• app.config.ts reçoit provideClientHydration(), pour que le navigateur réutilise le HTML au lieu de le reconstruire.

import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  isMainModule,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';
import express from 'express';
import { join } from 'node:path';

const browserDistFolder = join(import.meta.dirname, '../browser');

const app = express();
const angularApp = new AngularNodeAppEngine(); // une instance pour tout le serveur

// 1. (facultatif) vos API : app.get('/api/{*splat}', (req, res) => { ... });

// 2. Fichiers statiques (JS/CSS/images ont un hash dans leur nom → cache d’un an)
app.use(express.static(browserDistFolder, { maxAge: '1y', index: false, redirect: false }));

// 3. Tout le reste : Angular décide — HTML prérendu, SSR ou shell CSR
app.use((req, res, next) => {
  angularApp
    .handle(req)
    .then((response) => (response ? writeResponseToNodeResponse(response, res) : next()))
    .catch(next);
});

if (isMainModule(import.meta.url) || process.env['pm_id']) {
  const port = process.env['PORT'] || 4000;
  app.listen(port, (error) => {
    if (error) throw error;
    console.log(`Node Express server listening on http://localhost:${port}`);
  });
}

// utilisé par ng serve / ng build (et par certaines plateformes serverless)
export const reqHandler = createNodeRequestHandler(app);

Un détail dans server.ts : express.static a index: false, donc même / n’est pas servi directement depuis le disque. Chaque page passe par Angular, qui applique le render mode, les headers et le statut configurés pour la route.

Si vous avez un projet plus ancien dont le server.ts utilise CommonEngine : cette API est dépréciée depuis la v22, son remplaçant étant AngularNodeAppEngine (Node) ou AngularAppEngine (runtimes basés sur les Request/Response de la Web API).

RenderMode par route

import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  // Identique pour tous, ne change qu’au déploiement → HTML généré au build (SSG)
  { path: '', renderMode: RenderMode.Prerender },
  { path: 'despre', renderMode: RenderMode.Prerender },

  // Public, indexé, données qui changent souvent → rendu à chaque requête (SSR)
  { path: 'cautare', renderMode: RenderMode.Server },

  // Derrière la connexion : pas de SEO, HTML personnel → navigateur uniquement (CSR)
  { path: 'cont/**', renderMode: RenderMode.Client },

  // Le filet de sécurité pour toute route Angular non listée ci-dessus
  { path: '**', renderMode: RenderMode.Server },
];

Les règles qui comptent en pratique :

• Correspondance : un segment exact l’emporte sur un paramètre (:id), qui l’emporte sur **. Donc ** est le filet de sécurité, pas une règle qui « écrase ».
• Validation dans les deux sens : chaque route du routeur doit correspondre à une route serveur, et chaque route serveur (sauf celles qui se terminent par /**) doit exister dans le routeur. Sinon, le build s’arrête avec un message explicite.
• Le chemin ne commence pas par « / » — '/despre' est une erreur de build.
• Ce que reçoit le navigateur : Prerender → le fichier généré au build (avec un ETag) ; Server → le HTML rendu maintenant ; Client → index.csr.html, le shell vide, lui aussi servi par votre serveur.

import { PrerenderFallback, RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'produse/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const api = inject(CatalogApi); // synchrone, avant le await
      const items = await api.mostVisited(500);
      return items.map((x) => ({ id: String(x.id) }));
    },
    fallback: PrerenderFallback.Server,
  },
  // ...
];

Headers, statut et redirections

Chaque ServerRoute peut avoir des headers et un status. L’exception : les routes Prerender acceptent headers, mais pas status — le type ServerRoutePrerender l’exclut, car le fichier n’est généré qu’une seule fois. Les headers d’une page prérendue ne s’appliquent que lorsqu’elle est servie par le serveur Node, pas depuis un hébergement statique.

import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    // HTML public : le CDN peut le garder 60 s et servir l’ancienne version pendant qu’il se rafraîchit
    path: 'cautare',
    renderMode: RenderMode.Server,
    headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300' },
  },
  {
    // redirection permanente : { path: 'oferte', redirectTo: 'promotii' } dans app.routes.ts
    path: 'oferte',
    renderMode: RenderMode.Server,
    status: 301, // sans status : 302
  },
  {
    // prerender : headers oui, status NON (le type ServerRoutePrerender l’exclut)
    path: 'despre',
    renderMode: RenderMode.Prerender,
    headers: { 'X-Frame-Options': 'DENY' },
  },
  { path: '**', renderMode: RenderMode.Server },
];

Un redirectTo du routeur devient une vraie redirection HTTP sur le serveur (302 par défaut ; vous pouvez définir status: 301, 303, 307 ou 308), renvoyée sans rendre l’application. De même, si un guard redirige pendant le rendu (voir Guards & resolvers), l’URL finale diffère de l’URL demandée et le serveur répond par une redirection. Avec outputMode: 'static', où il n’y a pas de serveur, les redirections sont prérendues sous forme de « soft redirects » avec un <meta http-equiv="refresh"> dans le HTML.

Statut et headers décidés à l’exécution

Quand le statut dépend des données (le produit n’existe pas), vous le définissez depuis le composant via RESPONSE_INIT. Pour les cookies, la langue ou le user agent, vous lisez la requête via REQUEST. Les deux viennent de @angular/core et valent null dans le navigateur, au prerender et au build — gérez toujours le cas null.

import { Component, RESPONSE_INIT, inject } from '@angular/core';

@Component({
  selector: 'app-not-found',
  template: `<h1>Page introuvable</h1>`,
})
export default class NotFound {
  constructor() {
    // RESPONSE_INIT vaut null dans le navigateur, au prerender et au build → toujours vérifier.
    const response = inject(RESPONSE_INIT);
    if (response) response.status = 404; // le crawler voit 404, et non « 200 avec un texte d’erreur »
  }
}

Prerender avec paramètres

Les routes sans paramètres sont découvertes et prérendues automatiquement. Pour produse/:id, Angular ne peut pas deviner quels IDs existent, vous lui fournissez donc une fonction getPrerenderParams. Elle s’exécute au moment du build, dans un contexte d’injection (vous pouvez utiliser inject()), et renvoie une liste d’objets paramètre → valeur. Une route Prerender avec des paramètres mais sans getPrerenderParams arrête le build.

import { inject } from '@angular/core';
import { PrerenderFallback, RenderMode, ServerRoute } from '@angular/ssr';
import { ProductApi } from './products/product-api';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'produse/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const api = inject(ProductApi); // ✓ inject() synchrone, AVANT tout await
      const ids = await api.topProductIds(500); // s’exécute au BUILD, pas à la requête
      return ids.map((id) => ({ id: String(id) })); // les valeurs doivent être des chaînes
    },
    // /produse/9999 n’a pas été prérendu → que fait-on à la requête ?
    fallback: PrerenderFallback.Server, // par défaut : SSR à la requête
  },
  {
    path: 'blog/:slug/**', // paramètres + catch-all
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [{ slug: 'ssr', '**': 'partea/1' }]; // → /blog/ssr/partea/1
    },
  },
  { path: '**', renderMode: RenderMode.Server },
];

Ce qui arrive à une URL qui n’a pas été générée au build dépend de fallback :

Le coût est au moment du build : chaque URL est un rendu complet. Dix mille produits, c’est dix mille rendus à chaque déploiement et dix mille fichiers à téléverser. Si les données changent chaque jour, il faut aussi un build planifié qui les régénère.

Déploiement, cache et coûts

outputMode dans angular.json décide de ce que produit le build. Avec "server" (ce que définit ng add), vous obtenez dist/app/browser plus dist/app/server/server.mjs, et il vous faut un processus Node. Avec "static", vous n’obtenez que des fichiers : les pages prérendues et le shell CSR, déployables sur n’importe quel CDN. Une route RenderMode.Server en mode static est une erreur de build.

{
  "projects": {
    "magazin": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}

Les couches de cache

Le transfer cache est la raison pour laquelle, dans la timeline, le SSR ne refait plus la requête API depuis le navigateur : les données récupérées par HttpClient sur le serveur sont sérialisées dans <script id="ng-state"> et lues au démarrage. Ses options (withHttpTransferCacheOptions, withNoHttpTransferCache) se trouvent sur la page Hydration. Aussi : sur le serveur, avec le backend fetch par défaut, chaque réponse HTTP est limitée à 1 MB (erreur NG02825) ; la limite se modifie avec provideServerRendering({ maxResponseBodySize }, …).

Coût opérationnel

• CPU par requête : chaque rendu SSR est un bootstrap complet. Sans cache CDN, le trafic des bots se paie en serveurs.
• TTFB lié au backend : le serveur attend la stabilité, donc une API lente ralentit toutes vos pages. Mettez en place des timeouts et déplacez les données secondaires dans @defer (sur le serveur, un bloc sans trigger hydrate ne rend que le placeholder).
• Mémoire partagée entre les requêtes : le code est évalué une fois par processus, donc les variables au niveau du module et les providers useValue sont communs à tous les utilisateurs.
• Un système de plus en production : logs, monitoring, scaling, version de Node, cold start sur serverless.

import { InjectionToken } from '@angular/core';

// ✗ État au niveau du module : sur le serveur, le module est évalué UNE SEULE fois,
//    donc la variable est partagée par toutes les requêtes (et tous les utilisateurs).
let currentUser: string | null = null;

// ✗ useValue au niveau de l’application : la même valeur jusqu’au redémarrage du serveur.
export const RENDERED_AT = new InjectionToken<number>('RENDERED_AT');
const bad = { provide: RENDERED_AT, useValue: Date.now() };

// ✓ useFactory : s’exécute à chaque rendu (chaque requête a son propre injecteur).
const good = { provide: RENDERED_AT, useFactory: () => Date.now() };

// ✓ L’état par utilisateur vit dans des services (instanciés à chaque requête), pas dans des variables globales.

Quand OUI, quand NON

Pièges fréquents

• Cache public sur du HTML personnalisé → un utilisateur voit la page d’un autre. Sur les routes Server avec des données personnelles, utilisez Cache-Control: private, no-store.
• allowedHosts vide en production → 400 sur toutes les pages (v22). Configurez les domaines ou NG_ALLOWED_HOSTS.
• « Soft 404 » : le composant « not found » répond 200. Définissez status = 404 via RESPONSE_INIT.
• Mauvais fallback SPA sur un hébergement statique : avec le prerender, index.html est la page de la route /. Les routes Client doivent retomber sur index.csr.html.
• L’application ne devient pas stable : une PendingTask sans nettoyage (ou, avec Zone.js, un setInterval lancé dans la zone Angular) fait attendre le rendu, et la requête ne se termine jamais.
• Un CDN qui minifie le HTML et supprime les commentaires → l’hydration échoue avec NG0507. Les commentaires d’Angular sont nécessaires ; désactivez cette option sur le CDN.
• « J’ai ajouté du SSR et le TTI n’a pas bougé » — c’est normal : le JS est le même. Mesurez le LCP, pas le TTI, et réduisez le JS initial séparément.

Aide-mémoire

// ng new app --ssr  |  ng add @angular/ssr  |  ng build  |  node dist/app/server/server.mjs

// app.config.server.ts
provideServerRendering(withRoutes(serverRoutes));
provideServerRendering({ maxResponseBodySize: 5 * 1024 * 1024 }, withRoutes(serverRoutes)); // 1 MB par défaut

// app.config.ts (browser)
provideClientHydration();

// app.routes.server.ts — import { RenderMode, PrerenderFallback, ServerRoute } from '@angular/ssr'
export const serverRoutes: ServerRoute[] = [
  { path: 'despre', renderMode: RenderMode.Prerender }, // HTML au build (SSG)
  {
    path: 'produse/:id',
    renderMode: RenderMode.Prerender,
    getPrerenderParams: async () => [{ id: '1' }, { id: '2' }], // s’exécute au build
    fallback: PrerenderFallback.Server, // | Client | None — Server par défaut
  },
  { path: 'cautare', renderMode: RenderMode.Server, headers: { 'Cache-Control': 'no-store' } },
  { path: 'cont/**', renderMode: RenderMode.Client }, // shell vide, rendu dans le navigateur
  { path: '**', renderMode: RenderMode.Server }, // le filet de sécurité
];

// @angular/core — tous null dans le navigateur, au prerender et au build
inject(REQUEST); // Request : headers, cookies, URL
inject(RESPONSE_INIT); // ResponseInit : status / headers définis dynamiquement
inject(REQUEST_CONTEXT); // le deuxième argument de angularApp.handle(req, context)

// angular.json → architect.build.options
//   "outputMode": "server" | "static"               static = pas de Node : uniquement Prerender + Client
//   "security": { "allowedHosts": ["exemplu.ro"] }  host inconnu → 400 Bad Request (v22)