pnpm and the lockfile

package.json names version ranges, so two installs a week apart can get different packages. A lockfile records the exact version of every package, direct or indirect, and an install that follows it gets the same tree each time. Terrarium commits pnpm-lock.yaml, and both the Gate in CI and the live container refuse to install when it disagrees with package.json.

Know pnpm and lockfiles already? Skip to In Terrarium.

In Terrarium

package.json pins pnpm itself:

5  "packageManager": "pnpm@10.33.0",

CI's setup step, pnpm/action-setup, reads that field when it is given no version, and the live container's image enables Corepack, which reads it too (deploy/Dockerfile). Each range in package.json resolves to one exact version in pnpm-lock.yaml:

17      zod:
18        specifier: ^3.25.76
19        version: 3.25.76

Two installs refuse a lockfile that disagrees. The GateThe fixed set of machine checks every change must pass before it merges. It runs locally and in CI, and the CI run decides.GLOSSARY.md installs in .github/actions/gate/action.yml:

24    - name: Install
25      shell: bash
26      run: pnpm install --frozen-lockfile

The live container installs in deploy/entrypoint.sh, into a pnpm store on its volume:

57install_deps() {
58  rm -f "$INSTALLED_HASH"
59  log "pnpm install (frozen lockfile)…"
60  ( cd "$REPO_DIR" && pnpm install --frozen-lockfile --store-dir "$STORE_DIR" ) &&
61    lockhash > "$INSTALLED_HASH"
62}

It runs at first boot, and after a new commit only when the lockfile's hash differs from the one saved by the last good install (Continuous deployment follows that loop).

Local installs are plain. Each Claude Code session starts with pnpm install (.claude/settings.json), and pnpm gate:scoped runs one before its first step when package.json or the lockfile is newer than node_modules/.pnpm (scripts/gate/gate.ts).

The repo has no pnpm-workspace.yaml or .npmrc, and package.json has no pnpm field: pnpm runs on its defaults. Since pnpm 10 those skip every dependency's install scripts, the usual way a compromised package runs code (pnpm: Supply chain security): each install prints the ones it skipped, and pnpm ignored-builds lists them. The project's own postinstall runs: it points git at .githooks/ and runs nuxt prepare.

pnpm puts only a project's declared dependencies at the top of node_modules (pnpm: Motivation): Nuxt Content depends on jiti, which alone would leave it only in node_modules/.pnpm; package.json also declares jiti as a dev dependency of its own, which puts it at the top level, where shared/expand.ts imports it to load the manifests. package.json is on the Human-onlySaid of a file whose changes a person with write access must merge, whatever the Gate says. Agents may still edit it. The one exception is a minor or patch npm bump that Dependabot opens from the repo itself, that changes only package.json and the lockfile, and that stays within each package's major version (a 0.x minor counts as a major).GLOSSARY.md list (Protected paths); pnpm-lock.yaml is not.

Where next

• LessonContinuous deployment
• LessonProtected paths
• LessonMerge gate
• JournalArchitecture & Deployment