chore(memory): correct BLK-005 + LRN-022 — pnpm 11.x line needs Node 22
Initial hypothesis ("pnpm@latest pulled a newer 11.4+ with new Node
floor") was wrong. Investigation after the second VPS crash showed
the whole pnpm 11.0+ line imports node:sqlite from its store-index
module. Local dev was misleading because pnpm install never re-ran
on the Node 20 host (lockfile already resolved, child scripts don't
load the store module).
Updates:
- BLK-005: replace single-fix line with iteration log
(@latest → @11.1.3 → @10.13.1, last one resolved).
- LRN-022: rewrite headline + body to reflect pnpm 11 ↔ Node 22.13
coupling, not just pnpm 11.4. Add pnpm/Node compat matrix.
- journal 2026-05-21: append v2 fix entry referencing commit 990c8e7.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
990c8e700c
commit
dbd2bf30e9
3 files changed
+17
-10
No files matched your search
@@ -174,12 +174,14 @@ Apply: any data contract sourced from non-engineering authors (clinical, legal,
|
||||
|
||||
---
|
||||
|
||||
## LRN-022 | 2026-05-21 | Never floating `pnpm@latest` (or any unpinned tag) in Dockerfile — silent Node-version drift
|
||||
## LRN-022 | 2026-05-21 | pnpm 11.x requires Node 22.13 — pin pnpm to ≤10.x when staying on Node 20, never use `@latest`
|
||||
|
||||
`corepack prepare pnpm@latest --activate` re-resolves at every cold build. pnpm minor bumps can raise required Node floor without warning: pnpm 11.4 added `node:sqlite` import → Node 22.13+ required. Image stayed on `node:20-alpine` → `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` at install start. Works on dev host because corepack caches older pnpm (11.1.3); breaks on fresh VPS cold build that re-resolves `@latest`. Same trap for any unpinned upstream ref: `node:lts`, `:alpine`, `nginx:alpine`, GitHub Actions `uses: foo@v1` (prefer SHA).
|
||||
pnpm 11.x imports `node:sqlite` for its store-index module — loaded at pnpm startup for any command that touches the store (install, fetch, add, prune). `node:sqlite` is a Node 22.13+ built-in. Result: `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` on every fresh Docker build using `node:20-alpine` + pnpm 11.x. The crash is deterministic for cold installs and invisible for warm dev hosts that already have `node_modules` resolved (pnpm 11 on Node 20 can still spawn child scripts because the store module isn't required for `pnpm run`).
|
||||
Initial hypothesis ("pnpm@latest pulls a newer 11.x with a new Node floor") was wrong — the whole pnpm 11.0+ line carries the sqlite dependency.
|
||||
Fix paths:
|
||||
- Pin exact in Dockerfile: `corepack prepare pnpm@<X.Y.Z> --activate`.
|
||||
- Mirror in `package.json`: `"packageManager": "pnpm@X.Y.Z"` — host + Docker stay synced via corepack.
|
||||
- Bump base image deliberately when pnpm major bump is intentional, never as side effect of `@latest`.
|
||||
**Why:** Floating tag = drift bomb between cached dev + fresh prod resolve. CI passes today, prod breaks tomorrow on same Dockerfile, no commit changed.
|
||||
**How to apply:** Audit every Dockerfile + docker-compose + CI `uses:` for floating refs before first prod deploy. Lockfile pins app deps; Dockerfile + workflow files must pin toolchain.
|
||||
- Stay on Node 20 → pin Dockerfile to `pnpm@10.x` (e.g. `corepack prepare pnpm@10.13.1 --activate`). pnpm 10 reads lockfile v9 unchanged.
|
||||
- Move to Node 22 → bump `FROM node:22-alpine`, `.nvmrc`, and CLAUDE.md stack table together. Required if pnpm 11+ features needed.
|
||||
- Mirror exact version in `package.json`: `"packageManager": "pnpm@X.Y.Z"` so host + Docker stay synced via corepack.
|
||||
- Never `corepack prepare pnpm@latest` — re-resolves at every cold build, silently bumps toolchain across deploys with no commit.
|
||||
**Why:** Floating tag = drift bomb between cached dev + fresh prod resolve. Same risk for unpinned `node:lts`, `:alpine`, GitHub Actions `uses: foo@v1` (prefer SHA). Lockfile pins app deps; Dockerfile must pin toolchain.
|
||||
**How to apply:** Before first prod deploy, audit every Dockerfile, docker-compose, and CI workflow for floating upstream refs. For pnpm specifically, check Node version against pnpm minimum (pnpm 11 ↔ Node 22.13, pnpm 10 ↔ Node 18+, pnpm 9 ↔ Node 18+).
|
||||
Reference in new issue
Block a user