pnpm contributor guide

For anyone working on Mox JavaScript repos: command-tower, hero, brainstorming (UI).

We use pnpm 11 only. npm and yarn are blocked for installs.

One-time setup

corepack enable

If Corepack isn’t available:

npm install -g pnpm@11.3.0

Per repo

git pull
pnpm install

Run scripts with pnpm run … (not npm run …).

Repo	Common commands
command-tower	`pnpm dev`, `pnpm verify`
hero	`pnpm run dev`, `pnpm run build`
brainstorming (UI)	`pnpm --filter demo-ui run dev`, or `scripts/ci/smoke_ui.sh` from repo root

What happens if you use npm?

npm install
# → EBADDEVENGINES: packageManager must be pnpm

CI also rejects PRs that add package-lock.json or yarn.lock.

Supply-chain defaults (automatic)

Every repo uses a 3-day cooldown on newly published packages, plus trust and build-script checks. Config lives in each repo’s pnpm-workspace.yaml.

If pnpm add fails on a brand-new release, wait a few days or ask in chat before overriding policy.

Troubleshooting

Problem	Fix
`pnpm: command not found`	Run `corepack enable` or install pnpm 11 globally
Lockfile out of date in CI	Run `pnpm install`, commit `pnpm-lock.yaml`
Build scripts blocked	Run `pnpm approve-builds` once, commit updated `pnpm-workspace.yaml`

Questions?

Ping Shawn or open an issue in the repo you’re working in.