Server-Side Rendering

Relevant source files

Purpose and Scope

This document describes Angular's Server-Side Rendering (SSR) system provided by the @angular/platform-server package, which enables applications to render on a Node.js server. SSR produces fully-rendered HTML that can be sent to the client, improving initial load time, SEO, and accessibility adev/src/content/guide/ssr.md3

This page covers:

The @angular/platform-server package structure and APIs.
Server-side rendering pipeline and rendering context.
Integration with Node.js environments and routing via RenderMode.
The HTTP Transfer Cache mechanism for optimizing data fetching.
Configuration and setup for SSR applications.

Architecture Overview

Angular SSR operates in two distinct phases:

Server Phase: The Angular application renders on Node.js, producing HTML and serializing application state into the TransferState packages/platform-server/src/utils.ts197-208
Client Phase: The browser receives pre-rendered HTML and bootstraps the Angular application, reusing the serialized state via HttpTransferCache to avoid duplicate network requests packages/common/http/src/transfer_cache.ts191-210

SSR Architecture Overview

Sources: adev/src/content/guide/ssr.md31-53 packages/platform-server/src/utils.ts197-210 packages/common/http/src/transfer_cache.ts191-210

Platform-Server Package

The @angular/platform-server package provides the server platform implementation for Angular. It includes a server-specific DOM adapter (Domino) and rendering utilities.

Key Components:

Component	Purpose	File Path
`ServerModule`	Module for server platform setup	packages/platform-server/src/server.ts66-70
`provideServerRendering()`	Modern provider-based server configuration	packages/platform-server/src/server.ts77-81
`renderApplication()`	Async function to render application to HTML string	packages/platform-server/src/utils.ts197-210
`BEFORE_APP_SERIALIZED`	Injection token for hooks before serialization	packages/platform-server/src/tokens.ts64
`INITIAL_CONFIG`	Token for server configuration (URL, document)	packages/platform-server/src/tokens.ts65
`PlatformState`	Manages the server-side DOM state	packages/platform-server/src/platform_state.ts23

Server Platform Initialization:

Sources: packages/platform-server/src/server.ts61-70 packages/platform-server/src/location.ts27-56 packages/platform-server/src/tokens.ts64-65

Server-Side Rendering Pipeline

The server rendering pipeline transforms an Angular application into an HTML string. This involves bootstrapping the app, waiting for stability (asynchronous tasks), and serializing the result.

Rendering Process:

Rendering Context: The server environment uses ServerPlatformLocation to implement URL state without a browser history stack packages/platform-server/src/location.ts27-35 Angular also appends a ng-server-context attribute to the host elements of bootstrapped components to identify the rendering source packages/platform-server/src/utils.ts145-155

Sources: packages/platform-server/src/utils.ts55-74 packages/platform-server/src/utils.ts197-210 packages/platform-server/src/location.ts27-35

HTTP Transfer Cache

The HttpTransferCache feature recognizes duplicate requests between the server and client. It caches successful requests on the server and reuses them during hydration on the client to prevent "flicker" and redundant network traffic packages/common/http/src/transfer_cache.ts34-76

Transfer Cache Logic:

Option	Default	Description
`includePostRequests`	`false`	Enables caching for POST requests (e.g., for GraphQL) packages/common/http/src/transfer_cache.ts53-56
`includeHeaders`	`[]`	Specifies headers to include in the cached response packages/common/http/src/transfer_cache.ts48-50
`filter`	`undefined`	Custom function to include/exclude specific requests packages/common/http/src/transfer_cache.ts42-45
`includeRequestsWithAuthHeaders`	`false`	Enables caching of requests with `Authorization` or `Cookie` headers packages/common/http/src/transfer_cache.ts59-62

Request Origin Mapping: If the server uses an internal domain (e.g., http://internal-domain.com:8080) while the client uses a public one, the HTTP_TRANSFER_CACHE_ORIGIN_MAP token allows mapping these origins so the cache keys match packages/common/http/src/transfer_cache.ts79-106

Sources: packages/common/http/src/transfer_cache.ts34-76 packages/common/http/src/transfer_cache.ts104-106 packages/common/http/src/transfer_cache.ts147-178

Configuration and Server Routing

Angular provides a ServerRoute configuration to define rendering modes per path adev/src/content/guide/ssr.md29-53

Rendering Modes:

Mode	Description
`RenderMode.Server`	(SSR) Renders on the server for every request adev/src/content/guide/ssr.md90
`RenderMode.Client`	(CSR) Standard browser rendering adev/src/content/guide/ssr.md91
`RenderMode.Prerender`	(SSG) Renders at build time to static HTML adev/src/content/guide/ssr.md92

Configuration Example:

Sources: adev/src/content/guide/ssr.md31-53 adev/src/content/guide/ssr.md86-93

Transfer State Serialization

Application state is passed to the client via a script tag. Angular uses BEFORE_APP_SERIALIZED hooks to allow services to register data before the final HTML is generated packages/platform-server/src/tokens.ts64

Serialization Flow:

Sources: packages/platform-server/src/utils.ts205-208 packages/platform-server/src/transfer_state.ts33 packages/platform-server/src/tokens.ts64