Server-Side Rendering

Relevant source files

• .nvmrc
• adev/src/content/best-practices/BUILD.bazel
• adev/src/content/best-practices/a11y.md
• adev/src/content/best-practices/performance/BUILD.bazel
• adev/src/content/best-practices/style-guide.md
• adev/src/content/ecosystem/custom-build-pipeline.md
• adev/src/content/ecosystem/rxjs-interop/take-until-destroyed.md
• adev/src/content/guide/components/dom-apis.md
• adev/src/content/guide/components/inheritance.md
• adev/src/content/guide/drag-drop.md
• adev/src/content/guide/ssr.md
• adev/src/content/guide/templates/binding.md
• adev/src/content/guide/templates/ng-container.md
• adev/src/content/guide/templates/ng-content.md
• adev/src/content/guide/templates/overview.md
• adev/src/content/guide/templates/pipes.md
• adev/src/content/guide/templates/two-way-binding.md
• adev/src/content/guide/testing/component-harnesses-overview.md
• adev/src/content/guide/testing/component-harnesses-testing-environments.md
• adev/src/content/guide/testing/creating-component-harnesses.md
• adev/src/content/guide/testing/using-component-harnesses.md
• adev/src/content/introduction/essentials/dependency-injection.md
• adev/src/content/introduction/essentials/templates.md
• adev/src/content/reference/migrations/outputs.md
• adev/src/content/tutorials/first-app/steps/01-hello-world/README.md
• integration/platform-server/projects/ngmodule/src/app/http-transferstate-lazy/http-transfer-state.component.ts
• integration/platform-server/projects/standalone/src/app/http-transferstate-lazy/http-transfer-state.component.ts
• packages/common/http/src/transfer_cache.ts
• packages/common/http/test/transfer_cache_spec.ts
• packages/core/src/render3/util/transfer_state_utils.ts
• packages/core/src/transfer_state.ts
• packages/core/test/transfer_state_spec.ts
• packages/examples/core/ts/metadata/lifecycle_hooks_spec.ts
• packages/forms/BUILD.bazel
• packages/platform-browser/src/browser/browser_adapter.ts
• packages/platform-browser/test/hydration_spec.ts
• packages/platform-server/BUILD.bazel
• packages/platform-server/init/BUILD.bazel
• packages/platform-server/init/src/shims.ts
• packages/platform-server/init/test/BUILD.bazel
• packages/platform-server/init/test/shims_spec.ts
• packages/platform-server/src/domino_adapter.ts
• packages/platform-server/src/http.ts
• packages/platform-server/src/location.ts
• packages/platform-server/src/server.ts
• packages/platform-server/src/tokens.ts
• packages/platform-server/src/url.ts
• packages/platform-server/src/utils.ts
• packages/platform-server/test/BUILD.bazel
• packages/platform-server/test/integration_spec.ts
• packages/platform-server/test/platform_location_spec.ts
• packages/platform-server/test/transfer_state_spec.ts
• packages/platform-server/test/url_spec.ts
• packages/platform-server/test/utils_spec.ts
• packages/platform-server/third_party/domino/BUILD.bazel
• tools/bazel/tsec.bzl
• tools/tslint/tsNodeLoaderRule.js
• tsconfig-tslint.json

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
• The HTTP Transfer Cache mechanism for optimizing data fetching
• Configuration and setup for SSR applications

Architecture Overview

Angular SSR operates in two distinct phases:

1. Server Phase: Angular application renders on Node.js, producing HTML and serializing application state into the TransferState packages/platform-server/src/utils.ts195-208
2. Client Phase: Browser receives pre-rendered HTML and bootstraps the Angular application, reusing the serialized state to avoid duplicate work packages/common/http/src/transfer_cache.ts162-174

SSR Architecture Overview

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

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.ts
provideServerRendering()	Modern provider-based server configuration	packages/platform-server/src/server.ts
renderApplication()	Async function to render application to HTML string	packages/platform-server/src/utils.ts195-210
BEFORE_APP_SERIALIZED	Injection token for hooks before serialization	packages/platform-server/src/tokens.ts30
INITIAL_CONFIG	Token for server configuration (URL, document)	packages/platform-server/src/tokens.ts30

Server Platform Initialization:

Sources: packages/platform-server/src/server.ts packages/platform-server/src/location.ts27-56 packages/platform-server/src/tokens.ts30

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 element of bootstrapped components to identify the rendering source packages/platform-server/src/utils.ts143-153

Sources: packages/platform-server/src/utils.ts53-72 packages/platform-server/src/utils.ts195-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 GET/HEAD 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-56

Transfer Cache Logic:

Option	Default	Description
includePostRequests	false	Enables caching for POST requests (e.g., for GraphQL)
includeHeaders	[]	Specifies headers to include in the cached response
filter	undefined	Custom function to include/exclude specific requests
includeRequestsWithAuthHeaders	false	Enables caching of requests with Authorization or Cookie headers

Request Origin Mapping: If the server uses an internal domain (e.g., http://internal-api: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.ts59-84

Sources: packages/common/http/src/transfer_cache.ts51-56 packages/common/http/src/transfer_cache.ts84-86 packages/common/http/src/transfer_cache.ts127-147

Configuration and Server Routing

Angular provides a ServerRoute configuration to define rendering modes per path adev/src/content/guide/ssr.md31-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.ts30

Serialization Flow:

Sources: packages/platform-server/src/utils.ts203-208 packages/platform-server/src/transfer_state.ts31 packages/platform-server/src/tokens.ts30