SSR (Server-Side Rendering)

Priority: P2 (MEDIUM)

Principles

• Hydration: Run ng add @angular/ssr. In

  app.config.ts

  add provideClientHydration(withEventReplay()) to providers. This enables full app hydration where Angular reuses server-rendered DOM instead of wiping and re-rendering on the client.
• Platform Checks: Use afterNextRender(() => { /_ window access _/ }) or

  afterRender

  for browser-only code (e.g., accessing window, document, or localStorage). For recurring access, inject PLATFORM_ID and check isPlatformBrowser(platformId).
• TransferState: Use withHttpTransferCacheOptions() or manual TransferState service to prevent double-fetching by caching server responses for client replay.

Render Modes (Angular 17+)

Configure per-route via app.routes.server.ts by exporting ServerRoute[]:

• RenderMode.Prerender — Static HTML at build time (blogs, marketing)
• RenderMode.Server — Dynamic SSR per request (user-specific pages)
• RenderMode.Client — Client-only SPA (authenticated dashboards)

Incremental Hydration (Angular 19+)

Defer hydration of heavy components using @defer (hydrate on viewport):

• Triggers:

  viewport

  ,

  interaction

  ,

  idle

  ,

  timer(ms)

  ,

  immediate

  ,

  never

• Add withEventReplay() to

  provideClientHydration()

  to capture user events before hydration completes.

Guidelines

• Browser Objects: Never access window directly in component logic. Implement abstractions or use

  afterNextRender

  .
• Prerendering: Use

  getPrerenderParams()

  in server routes to enumerate dynamic slugs.

Anti-Patterns

• No direct window/document access: Use

  afterNextRender()

  or

  PLATFORM_ID

  check for browser APIs.
• No double-fetching: Use

  withHttpTransferCacheOptions()

  or

  TransferState

  to avoid re-fetching on client.
• No SSR for auth-gated pages: Set

  RenderMode.Client

  for authenticated dashboards.

References

• Hydration