pnpm-workspace.yaml catalogs. Toolchain binaries (Node, pnpm, gitleaks) are pinned in mise.toml. Nothing else carries a version.
Catalogs
A member’spackage.json names the catalog, never a version:
package.json
- Catalog entries are named by role and cadence, not by one consumer. Toolchain that builds output (
build) has a different risk and cadence than lint and test tools (quality). - Workspace packages use
workspace:*. Peer ranges state a compatible range for consumers and are the only literal versions allowed. - A version is added to a catalog first, then referenced. Check for an existing entry before adding one; never add a caret range “temporarily” in a member.
- A pin that must differ from a catalog’s line says why in a comment next to the entry (for example
reactinmobilestays on the exact version React Native renders with). - A catalog entry declared ahead of its first consumer is allowed;
knipreports a dead one as a warning.
Toolchain pins
mise.toml pins node, pnpm and gitleaks. The pnpm pin must equal packageManager in the root package.json: corepack reads that one, and a mismatch is a bug, not a choice. .node-version and engines agree with it. CI installs the toolchain from these files (see CI).
Install-time controls
Adding an entry to
allowBuilds or minimumReleaseAgeExclude is as serious as adding a dependency: it names a reason in the change, and the dependency-steward reviews it. An advisory fix on a critical vulnerability may bypass the release age; nothing else does.
Licences
Every dependency’s licence must be on the allow-list. The policy is a data file reviewed by code owners:
A denied licence is fixed by replacing the dependency, never by editing the policy in the same change. The member’s own
license is MIT (0024) (Members).
Forbidden dependencies
The validator rejects a manifest that depends on a package the architecture rejected:eslint, prettier, jest, @nestjs/*, reflect-metadata, prisma, drizzle-orm, express, fastify, typeorm, knex. Each has a recorded replacement and revival trigger in ADR 0011.
Adding a dependency
1
Check licence and need
Confirm the licence is allowed and the package is not already covered by one in the repo.
2
Add it to a catalog
Add the package and version under the right catalog in
pnpm-workspace.yaml.3
Reference it
pnpm add <pkg>@catalog:<name> --filter <package-name>4
Review install scripts
If install fails with
ERR_PNPM_IGNORED_BUILDS, decide true or false in allowBuilds and say why.5
Verify
pnpm verify; add a changeset when a published package changes.