ADR 001: Use Nx Monorepo with npm
Status: Accepted
Date: 2026-05-23
Context
Synapse UI is a multi-package Angular component library with shared utilities, a theme system, multiple UI entry points, a documentation site, and a sandbox app. We need a monorepo tool that supports:
- Independent versioning and publishing of
@synapse-ui/*packages - Affected-based CI (only build/test what changed)
- Consistent code generators for new components
- Shared TypeScript configuration and lint rules
We also need to choose a package manager. The project targets open-source contributors who may not have pnpm or yarn installed globally.
Decision
Use Nx as the monorepo orchestrator with npm as the package manager.
Consequences
Positive
- Nx provides first-class Angular support, generators, and
ng-packagrintegration. nx affecteddramatically reduces CI time as the library grows.- npm is the default Node.js package manager — lowest barrier for open-source contributors.
- Nx module boundary enforcement prevents circular dependencies between libs.
Negative
- Nx adds configuration overhead compared to a single-package repo.
- npm is slower than pnpm for large dependency trees (acceptable for this project size).
- Developers must learn Nx CLI conventions alongside Angular CLI.
Alternatives Considered
| Alternative | Why rejected |
|---|---|
| pnpm workspaces | Faster installs, but adds tooling prerequisite for contributors |
| yarn workspaces | Less common in Angular ecosystem; Berry vs Classic confusion |
| Lerna (standalone) | Lacks Nx's affected graph, generators, and Angular integration |
| Single package repo | Cannot publish granular @synapse-ui/* entry points cleanly |