---
status: accepted
date: 2026-04-29
decision-makers: R&D Lead
tags: [frontend]
---

# Frontend stack — Angular (latest LTS), standalone, zoneless, Signals, CSR-only, Vitest

## Context and Problem Statement

The portal's frontend (`portal-shell`) is a single-page application that aggregates access to existing applications and progressively integrates re-developed features. It sits fully behind authentication: no public content. We need to fix the framework, the rendering mode, the change-detection model, and the test runner now, so subsequent ADRs (auth flow, observability, accessibility, performance budgets) can build on a stable foundation.

What frontend stack maximizes alignment with our backend (NestJS), gives us first-class accessibility and performance hooks, and is enterprise-stable for a long-lived project?

## Decision Drivers

* Architectural alignment with NestJS (DI, decorators, modules, RxJS) — minimizes cognitive distance for the team.
* Performance and accessibility as first-class concerns from day one.
* Long-term enterprise stability (no pre-1.0, no exotic stack).
* End-to-end type safety.
* No public surface — all content gated by authentication, which removes the usual SSR drivers (SEO, anonymous LCP).

## Considered Options

* **Angular (latest LTS) — standalone, zoneless, Signals, CSR, Vitest.** (Chosen.)
* Angular with SSR (`@angular/ssr`).
* React + Next.js (or Vite + React Router).
* Vue + Nuxt.
* Svelte + SvelteKit.

## Decision Outcome

Chosen option: **Angular at the latest LTS major**, with the following modern defaults:

* **Standalone APIs** — no `NgModule`s. Configuration is composed via providers; routing is functional.
* **Zoneless change detection** — no `Zone.js`. Change detection is driven by Signals and explicit `markForCheck` where needed.
* **Signals** — primary reactive primitive for component state. RxJS retained for async streams (HTTP, events).
* **Vitest** — unit and component test runner (Karma is deprecated upstream).
* **CSR only — no SSR** for v1. Reconsider only if a measured performance metric requires it.
* **SCSS** for styles. Design-token strategy to be defined in a future ADR.
* **Strict TypeScript** across the workspace (`strict: true`, `noUncheckedIndexedAccess: true`).

### Consequences

* Good, because the team works with a single mental model across front and back (DI, decorators, RxJS).
* Good, because zoneless + Signals removes Zone.js overhead and gives finer-grained, more predictable reactivity.
* Good, because Vitest is significantly faster than Karma and shares the Vite toolchain Nx already uses.
* Good, because CSR keeps the BFF free of SSR concerns (no auth-aware rendering, no double-fetch, no hydration debugging) — simpler operational surface.
* Bad, because Angular's release cadence is brisk; the project commits to staying on LTS rather than skipping versions.
* Bad, because zoneless and Signals are recent — though stable, the broader Angular ecosystem still includes Zone-dependent libraries that must be vetted before adoption.
* Bad, because CSR yields a minimal initial HTML payload; this must be paired with strong performance budgets (covered by ADR-0015, future).

### Confirmation

* `package.json` pins Angular to the current LTS major.
* `app.config.ts` registers `provideZonelessChangeDetection()` (or its current stable equivalent) and standalone routing.
* `tsconfig.base.json` sets `strict: true` and `noUncheckedIndexedAccess: true`.
* CI runs `pnpm nx test portal-shell` (Vitest).
* No `import 'zone.js'` anywhere in the codebase.
* `@angular/ssr` is not installed.

## Pros and Cons of the Options

### Angular CSR (chosen)

* Good, because alignment with NestJS minimizes context-switching for the team.
* Good, because mature, enterprise-supported (Google + community).
* Good, because Signals + zoneless make Angular's reactivity competitive with React/Vue.
* Bad, because verbosity is higher than minimalist frameworks.

### Angular SSR

* Good, because better TTFB and accessibility on first paint for unauthenticated content.
* Bad, because we have no unauthenticated content — the gain is essentially zero.
* Bad, because SSR-with-auth introduces non-trivial complexity (cookie-aware fetch, hydration with secured data).

### React + Next.js

* Good, because large ecosystem, fast iteration.
* Bad, because no architectural alignment with NestJS — different DI/state paradigms.
* Bad, because Next.js's defaults push toward server components and edge rendering, which conflict with our on-prem, all-authenticated profile.

### Vue + Nuxt / Svelte + SvelteKit

* Good, because lighter syntax, strong DX.
* Bad, because no DI alignment with NestJS.
* Bad, because smaller enterprise-grade community than Angular or React.

## More Information

* Angular zoneless change detection: https://angular.dev/guide/experimental/zoneless
* Angular Signals: https://angular.dev/guide/signals
* Vitest with Nx: https://nx.dev/nx-api/vite
* Related ADRs: [ADR-0005](0005-backend-stack-nestjs.md), ADR-0008 (auth flow, future), ADR-0014 (accessibility, future), ADR-0015 (performance budgets, future).