SSR, prerender & render modes

By default, Angular delivers the application as CSR (client-side rendering): the server sends an empty <app-root></app-root>, and the browser has to download, parse and run all the JavaScript — and then fetch the data too — before it shows anything useful. SSR (rendering on the server, on each request) and SSG (prerender, at build time) move the first render elsewhere: the user receives HTML with content straight away.

With @angular/ssr you don’t choose once for the whole application, but per route: the file app.routes.server.ts says for each path whether it is RenderMode.Prerender, RenderMode.Server or RenderMode.Client. This is called hybrid rendering. The server routes API appeared in v19 and has been stable since v20.

Three rendering modes

What the server concretely does in Server mode: for each request, @angular/ssr creates a new platform, calls the bootstrap function from main.server.ts, lets the router navigate to the URL, waits for the application to become stable (all HTTP requests and PendingTasks finished), serialises the DOM into HTML and destroys the application. The practical consequence: the TTFB of an SSR page is at least as long as the slowest API called during rendering.

In a real hybrid application the modes coexist: the homepage and the marketing pages are prerendered, search is rendered on the server, and the account area runs only in the browser.

What happens on a request

Five moments matter, in the order the user experiences them:

• TTFB (time to first byte) — the first byte of the HTML response.
• FCP (first contentful paint) — the first text or the first image on screen.
• LCP (largest contentful paint) — the main element appears (the title, the product image). It’s the metric the user feels as “it has loaded”.
• Hydration — the JS has arrived, Angular takes over the existing HTML and attaches the listeners.
• Interactive — a click actually does something. From this moment INP matters (how quickly the page responds).

With SSR and SSG, between LCP and “interactive” there is a window in which the page looks ready, but the buttons don’t have a listener yet. On a modest phone, with a bundle of a few hundred KB, the window easily lasts 1–3 seconds. Run the simulation and compare the three modes on the same network.

Notice what does not change: main.js is the same size in all three modes. SSR doesn’t shrink the JavaScript, so interactivity comes at about the same time as with CSR — sometimes even a little later, because the HTML is bigger and hydration costs CPU too. The real gain is the LCP. To shrink the non-interactive window: less initial JS (lazy routes, @defer), incremental hydration and event replay, which doesn’t lose the clicks made in the window.

What a crawler sees

A crawler starts from the HTML it receives (what you see with View source, not in the Elements tab). With CSR, that HTML is identical for any URL. Googlebot can run JavaScript, but at a later stage and with limits; bots that generate previews in chats and social networks usually read only the initial HTML. There is one detail that is often ignored: the status code. A static server doesn’t know that /produse/9999 doesn’t exist, so it answers 200 — a “soft 404”.

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

The title and meta tags are set with the Title and Meta services from @angular/platform-browser. They work through DOCUMENT, so they also work on the server: whatever you set during rendering ends up in the HTML that is sent. For pages without data, the route’s title property is enough (or your own TitleStrategy, if you want a common format).

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>(); // from the route produse/:id (withComponentInputBinding)

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

  constructor() {
    // Runs on the server too: the tags end up in the HTML sent to the crawlers.
    effect(() => {
      if (!this.product.hasValue()) return;
      const p = this.product.value();
      this.title.setTitle(`${p.name} — Shop`);
      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 });
    });
  }
}

Setup: what ng add generates

# new project, with SSR + prerender configured from the start
ng new magazin --ssr

# existing project: add @angular/ssr, express and the server files
ng add @angular/ssr

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

# start the Node server (script added by ng add in package.json)
npm run serve:ssr:magazin        # = node dist/magazin/server/server.mjs

The command adds the dependencies (@angular/ssr, express), four files and a few options in angular.json. It’s worth knowing what each one does, because you will modify them:

• server.ts — the Express server. It serves the static files from dist/…/browser, and gives the rest of the requests to AngularNodeAppEngine.handle(), which returns a Response (or null if the URL isn’t an Angular route). The reqHandler export is used by the CLI: ng serve renders on the server too.
• main.server.ts — the bootstrap function the server calls on every render.
• app.config.server.ts — provideServerRendering(withRoutes(serverRoutes)), combined with the browser config through mergeApplicationConfig.
• app.routes.server.ts — the render mode per route. By default, everything is Prerender.
• app.config.ts gets provideClientHydration(), so the browser reuses the HTML instead of rebuilding it.

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(); // one instance for the whole server

// 1. (optional) your APIs: app.get('/api/{*splat}', (req, res) => { ... });

// 2. Static files (JS/CSS/images have a hash in the name → one-year cache)
app.use(express.static(browserDistFolder, { maxAge: '1y', index: false, redirect: false }));

// 3. Anything else: Angular decides — prerendered HTML, SSR or the CSR shell
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}`);
  });
}

// used by ng serve / ng build (and by some serverless platforms)
export const reqHandler = createNodeRequestHandler(app);

A detail in server.ts: express.static has index: false, so not even / is served directly from disk. Every page goes through Angular, which applies the render mode, the headers and the status configured for the route.

If you have an older project whose server.ts uses CommonEngine: that API is deprecated since v22, its replacement being AngularNodeAppEngine (Node) or AngularAppEngine (runtimes based on the Web API Request/Response).

RenderMode per route

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

export const serverRoutes: ServerRoute[] = [
  // The same for everyone, changes only at deploy → HTML generated at build time (SSG)
  { path: '', renderMode: RenderMode.Prerender },
  { path: 'despre', renderMode: RenderMode.Prerender },

  // Public, indexed, data that changes often → rendered on every request (SSR)
  { path: 'cautare', renderMode: RenderMode.Server },

  // Behind the login: no SEO, personal HTML → browser only (CSR)
  { path: 'cont/**', renderMode: RenderMode.Client },

  // The safety net for any Angular route not listed above
  { path: '**', renderMode: RenderMode.Server },
];

The rules that matter in practice:

• Matching: an exact segment beats a parameter (:id), which beats **. So ** is the safety net, not a rule that “overrides”.
• Two-way validation: every route in the router must match a server route, and every server route (except those ending in /**) must exist in the router. Otherwise the build stops with an explicit message.
• The path doesn’t start with “/” — '/despre' is a build error.
• What the browser receives: Prerender → the file generated at build time (with an ETag); Server → HTML rendered now; Client → index.csr.html, the empty shell, also served by your server.

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

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

Headers, status and redirects

Each ServerRoute can have headers and status. The exception: Prerender routes accept headers, but not status — the ServerRoutePrerender type excludes it, because the file is generated only once. The headers of a prerendered page apply only when it is served through the Node server, not from static hosting.

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

export const serverRoutes: ServerRoute[] = [
  {
    // Public HTML: the CDN can keep it for 60 s and serve the old version while it refreshes
    path: 'cautare',
    renderMode: RenderMode.Server,
    headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300' },
  },
  {
    // permanent redirect: { path: 'oferte', redirectTo: 'promotii' } in app.routes.ts
    path: 'oferte',
    renderMode: RenderMode.Server,
    status: 301, // without status: 302
  },
  {
    // prerender: headers yes, status NO (the ServerRoutePrerender type excludes it)
    path: 'despre',
    renderMode: RenderMode.Prerender,
    headers: { 'X-Frame-Options': 'DENY' },
  },
  { path: '**', renderMode: RenderMode.Server },
];

A redirectTo from the router becomes a real HTTP redirect on the server (302 by default; you can set status: 301, 303, 307 or 308), answered without rendering the application. Likewise, if a guard redirects during rendering (see Guards & resolvers), the final URL differs from the requested one and the server answers with a redirect. With outputMode: 'static', where there is no server, redirects are prerendered as “soft redirects” with a <meta http-equiv="refresh"> in the HTML.

Status and headers decided at runtime

When the status depends on data (the product doesn’t exist), you set it from the component through RESPONSE_INIT. For cookies, language or user agent you read the request through REQUEST. Both come from @angular/core and are null in the browser, at prerender and at build time — always handle the null case.

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

@Component({
  selector: 'app-not-found',
  template: `<h1>Page not found</h1>`,
})
export default class NotFound {
  constructor() {
    // RESPONSE_INIT is null in the browser, at prerender and at build → always check.
    const response = inject(RESPONSE_INIT);
    if (response) response.status = 404; // the crawler sees 404, not “200 with an error text”
  }
}

Prerender with parameters

Routes without parameters are discovered and prerendered automatically. For produse/:id, Angular can’t guess which IDs exist, so you give it a function getPrerenderParams. It runs at build time, in an injection context (you can use inject()), and returns a list of parameter objects → value. A Prerender route with parameters but without getPrerenderParams stops the 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); // ✓ synchronous inject(), BEFORE any await
      const ids = await api.topProductIds(500); // runs at BUILD time, not on request
      return ids.map((id) => ({ id: String(id) })); // the values must be strings
    },
    // /produse/9999 was not prerendered → what do we do on request?
    fallback: PrerenderFallback.Server, // default: SSR on request
  },
  {
    path: 'blog/:slug/**', // parameters + catch-all
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [{ slug: 'ssr', '**': 'partea/1' }]; // → /blog/ssr/partea/1
    },
  },
  { path: '**', renderMode: RenderMode.Server },
];

What happens to a URL that wasn’t generated at build time depends on fallback:

The cost is at build time: every URL is a full render. Ten thousand products mean ten thousand renders on every deploy and ten thousand files to upload. If the data changes daily, you also need a scheduled build that regenerates them.

Deploy, cache and costs

outputMode in angular.json decides what the build produces. With "server" (what ng add sets) you get dist/app/browser plus dist/app/server/server.mjs, and you need a Node process. With "static" you get only files: prerendered pages and the CSR shell, deployable on any CDN. A RenderMode.Server route in static mode is a build error.

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

The cache layers

The transfer cache is the reason why, in the timeline, SSR no longer makes the API request from the browser: the data fetched by HttpClient on the server is serialised into <script id="ng-state"> and read at startup. Its options (withHttpTransferCacheOptions, withNoHttpTransferCache) are on the Hydration page. Also: on the server, with the default fetch backend, each HTTP response is limited to 1 MB (error NG02825); the limit changes with provideServerRendering({ maxResponseBodySize }, …).

Operational cost

• CPU per request: each SSR render is a full bootstrap. Without a CDN cache, bot traffic is paid for in servers.
• TTFB tied to the backend: the server waits for stability, so a slow API slows down all your pages. Put timeouts in place and move secondary data into @defer (on the server, a block without a hydrate trigger renders only the placeholder).
• Memory shared between requests: the code is evaluated once per process, so module-level variables and useValue providers are common to all users.
• One more system in production: logs, monitoring, scaling, Node version, cold start on serverless.

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

// ✗ Module-level state: on the server the module is evaluated ONCE,
//    so the variable is shared by all requests (and all users).
let currentUser: string | null = null;

// ✗ useValue at application level: the same value until the server restarts.
export const RENDERED_AT = new InjectionToken<number>('RENDERED_AT');
const bad = { provide: RENDERED_AT, useValue: Date.now() };

// ✓ useFactory: runs on every render (each request has its own injector).
const good = { provide: RENDERED_AT, useFactory: () => Date.now() };

// ✓ Per-user state lives in services (instantiated per request), not in global variables.

When YES, when NO

Common pitfalls

• Public cache on personalised HTML → one user sees another user’s page. On Server routes with personal data use Cache-Control: private, no-store.
• Empty allowedHosts in production → 400 on all pages (v22). Configure the domains or NG_ALLOWED_HOSTS.
• “Soft 404”: the “not found” component answers 200. Set status = 404 through RESPONSE_INIT.
• Wrong SPA fallback on static hosting: with prerender, index.html is the page of the / route. Client routes must fall back to index.csr.html.
• The application doesn’t become stable: a PendingTask without cleanup (or, with Zone.js, a setInterval started in the Angular zone) keeps the rendering waiting, and the request never finishes.
• A CDN that minifies the HTML and strips comments → hydration fails with NG0507. Angular’s comments are needed; disable the option on the CDN.
• “I added SSR and TTI stayed the same” — that’s normal: the JS is the same. Measure the LCP, not the TTI, and reduce the initial JS separately.

Cheat sheet

// 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)); // default 1 MB

// 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 at build (SSG)
  {
    path: 'produse/:id',
    renderMode: RenderMode.Prerender,
    getPrerenderParams: async () => [{ id: '1' }, { id: '2' }], // runs at build
    fallback: PrerenderFallback.Server, // | Client | None — default Server
  },
  { path: 'cautare', renderMode: RenderMode.Server, headers: { 'Cache-Control': 'no-store' } },
  { path: 'cont/**', renderMode: RenderMode.Client }, // empty shell, rendered in the browser
  { path: '**', renderMode: RenderMode.Server }, // the safety net
];

// @angular/core — all null in the browser, at prerender and at build
inject(REQUEST); // Request: headers, cookies, URL
inject(RESPONSE_INIT); // ResponseInit: status / headers set dynamically
inject(REQUEST_CONTEXT); // the second argument of angularApp.handle(req, context)

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