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

# Adopt Nx monorepo with the `apps` preset

## Context and Problem Statement

`apf-portal` will host two cooperating runtime artifacts from day one — an Angular SPA frontend and a Node.js BFF backend — and is expected to grow with feature libraries shared between them (auth, data-access, UI primitives). Strongly-typed contracts must travel from back to front without round-tripping through a published package, dependency hygiene must be enforceable, and CI must run only on what changed.

How do we structure the repository so both apps coexist with shared libraries, builds and tests run incrementally, and the tooling is mainstream enough to be supported long-term?

## Decision Drivers

- Two cooperating runtimes (Angular + NestJS), both TypeScript, sharing types and contracts on the wire.
- Need for incremental, cached builds and tests on what changed (`affected`-style workflow).
- Long-term enterprise track record — no exotic stack.
- Compatibility with `pnpm` (already mandated by project setup).
- Enforceable dependency boundaries between apps and libs.

## Considered Options

- **Polyrepos** — separate repository per runtime.
- **Nx with the `apps` preset** — generic multi-tech workspace, plugins added as needed (`@nx/angular`, `@nx/nest`).
- **Nx with the `angular-monorepo` preset** — front-first preset, BFF grafted on later.
- **Turborepo + pnpm workspaces** — lighter alternative to Nx.
- **pnpm workspaces alone** — manual orchestration, no monorepo tool.

## Decision Outcome

Chosen option: **Nx monorepo with the `apps` preset, managed by pnpm**.

The workspace will host:

- `apps/portal-shell` — Angular SPA frontend (see [ADR-0004](0004-frontend-stack-angular-csr-zoneless-signals.md));
- `apps/portal-bff` — NestJS BFF backend (see [ADR-0005](0005-backend-stack-nestjs.md));
- `libs/shared/<scope>` and `libs/feature/<name>` for shared and feature code (see [ADR-0003](0003-workspace-and-app-naming-convention.md)).

Plugins enabled at bootstrap: `@nx/angular`, `@nx/nest`, `@nx/eslint`, `@nx/vite` (Vitest).

### Consequences

- Good, because front and back share types, lint config, formatter, and test runner with no extra plumbing.
- Good, because Nx's project graph + `affected` make CI fast and frugal as the codebase grows.
- Good, because the `apps` preset stays neutral — neither runtime is privileged in workspace structure.
- Good, because Nx is mainstream, used by major enterprises, and actively maintained by Nrwl.
- Bad, because Nx adds a non-trivial conceptual surface (executors, generators, project graph) — a one-time learning cost.
- Bad, because monorepos require discipline to keep dependency boundaries clean — mitigated by Nx's `enforce-module-boundaries` lint rule.

### Confirmation

- Workspace is bootstrapped with `pnpm dlx create-nx-workspace@latest apf-portal --preset=apps --pm=pnpm`.
- `nx.json` has `@nx/eslint/enforce-module-boundaries` enabled and configured against the project tags.
- CI runs `pnpm nx affected -t lint test build` on every push.

## Pros and Cons of the Options

### Polyrepos

- Good, because each runtime has independent versioning and CI scope.
- Bad, because sharing TypeScript types across repos requires a published package (overhead, version drift).
- Bad, because cross-cutting changes (e.g. adjusting an auth claim shape) touch two repos and two PRs.

### Nx with `apps` preset (chosen)

- Good, because runtime-agnostic — Angular and Node coexist as peers.
- Good, because Nx provides build orchestration, caching, generators, and lint boundaries out of the box.

### Nx with `angular-monorepo` preset

- Good, because faster initial setup for a front-first project.
- Bad, because the preset implies the project is "an Angular workspace" — the BFF feels grafted, the workspace `package.json` ends up biased toward Angular tooling.

### Turborepo

- Good, because lighter, no codegen surface.
- Neutral, because caching/affected is comparable.
- Bad, because no first-class Angular plugin; both runtimes would need manual integration.
- Bad, because smaller enterprise track record than Nx.

### pnpm workspaces alone

- Good, because no extra tool to learn.
- Bad, because no caching, no `affected`, no generators — every piece reinvented by hand (the bricolage we're forbidden).

## More Information

- Nx documentation: https://nx.dev
- Nx `apps` preset: https://nx.dev/getting-started/intro
- Related ADRs: [ADR-0003](0003-workspace-and-app-naming-convention.md), [ADR-0004](0004-frontend-stack-angular-csr-zoneless-signals.md), [ADR-0005](0005-backend-stack-nestjs.md), ADR-0017 (CI/CD, future).
