ADR-002-b — Frontend Development Stack

Status

Accepted

Context

The frontend runs on Bun directly on the host (outside Docker) during development. Bun replaces npm as the package manager and script runner — faster at install and script execution. The build system remains @angular/build (esbuild internally); Bun acts as the script runtime and dependency manager.

Decision

Pinned dependency versions. The frontend stack is locked to the versions below. These are the only permitted versions; updates require a new ADR.

Component	Pinned version	Notes
Bun	`>=1.1`	Replaces npm. Package manager + script runner.
Angular	`^21.2.4`	Standalone, signals, `@angular/build`
TypeScript	`~5.9.2`	Pinned with `~`; no minor jumps
PrimeNG	`^21.1.3`	UI component library. Lara/Noir/Zinc.
`@primeuix/themes`	`^2.0.3`	Token system for PrimeNG v21
Tailwind CSS	`^4.2.1`	Utility layer. Not the design system — PrimeNG is ([[adr-012-design-system
`tailwindcss-primeui`	`^0.6.1`	Bridge tokens PrimeNG <-> Tailwind
Vitest	`^4.0.8`	Test runner. No Jest.
RxJS	`^7.8.0`	Only for HTTP interop; not for state
PrimeIcons	`^7.0.0`	Icon library for PrimeNG components
marked	`^17.0.5`	Markdown parser (changelog rendering)
PostCSS	`^8.5.8`	Build pipeline required by Tailwind v4

Bun is the only permitted execution method. Neither npm, npx, nor pnpm is used. The lockfile is bun.lock (text format). All scripts are invoked via Bun:

cd frontend
bun install        # install dependencies (updates bun.lock, text format)
bun start          # dev server on :4200 with proxy to :8000
bun test           # vitest
bun run build      # production build

Consequences

package.json scripts are invoked with bun run <script> or directly with bun <script> when there is no ambiguity.
tailwindcss-primeui ensures PrimeNG tokens are accessible as Tailwind utilities; never use Tailwind colors directly in templates.
RxJS remains as a dependency because HttpClient requires it internally; application code does not use .subscribe() for state.
In production ([[adr-003-b-frontend-prod-stack|ADR-003-b]]), AWS Amplify uses Bun if the build command is configured as bun run build in the Amplify Console.