Node's version lives in six hardcoded places; the single source of truth was removed to unblock a floor bump

[FrameAutomata]

Raised while reviewing #332 (closes #330). Not folded into that PR, because resolving it means reversing a deliberate decision made in f95424cc and that is a maintainer's call.

What happened

f95424cc ("node version fixes") did three linked things:

• frontend/package.json: engines.node "22.x" → ">=22"
• release-traceway.yml: deleted node-version-file: frontend/package.json, replaced with a literal node-version: 22
• flake.nix:29: patched the regex from ([0-9]+).* to [^0-9]*([0-9]+).* so it survives the leading >=

The causal chain is sound and the comment left behind states it plainly: setup-node's node-version-file reads engines.node and resolves it as a semver range to the newest satisfying release. "22.x" pinned the major; ">=22" silently means latest. Loosening the floor broke the pin, and the fix taken was to drop the mechanism and hardcode.

#332 then followed that precedent at two more sites (release-docs.yml, release-website.yml, both previously node-version: "latest").

Why it's worth revisiting

Node's major is now named literally in six places with nothing asserting they agree:

site	value
.github/workflows/release-traceway.yml:67	22
.github/workflows/release-docs.yml	22
.github/workflows/release-website.yml	22
.github/workflows/benchmark-processor.yml:88	22
Dockerfile, Dockerfile.minimal, Dockerfile.sqlite, Dockerfile.duckdb, Dockerfile.browser:18	node:22-alpine
Dockerfile.browser:57	node:22-bookworm-slim

Compare the Go convention in the same repo: 14 of 15 Go version references use go-version-file: against a go.mod. Only benchmark-hardware.yml:154 hardcodes. Node is the outlier.

This is also the pin-drift shape #330 was about. testing/devtesting-nestjs/Dockerfile is already on node:20-alpine — drift that exists today and that nothing reports.

Option worth considering

A root .nvmrc containing 22, with node-version-file: .nvmrc at all four setup-node sites. node-version-file and cache-dependency-path are independent inputs, so the existing cache-dependency-path: docs/package-lock.json etc. are unaffected.

engines.node: ">=22" then stays what >= is actually for — the npm-enforced floor — while .nvmrc carries the pin. flake.nix could read .nvmrc directly and the regex workaround from f95424cc deletes itself.

Two things this deliberately would not fix: the Dockerfiles (Docker can't read .nvmrc without ARG plumbing from the caller, five files plus a consistency check — genuinely separate), and docs/pages/client/js-sdk/sourcemap-upload.mdx:93, which should stay a literal since it is a copy-pasteable recipe for readers who have no .nvmrc.

Worth deciding either way: if hardcoding is the intended long-term shape, that is fine, but then the six sites want something that notices when they disagree — which is the same gap #330 opened.

[dusanstanojeviccs]

Real, should be tighter, we can lock it down to like 26

[FrameAutomata]

Done in #346, at 26 as you suggested.

.nvmrc is now the source of truth: the four setup-node steps read it, flake.nix reads it, and release-traceway.yml passes it to all five image builds as --build-arg NODE_VERSION. The Dockerfiles keep an ARG default because a bare docker build can't read .nvmrc — that default is the only value left that can drift, so scripts/check-node-pins.sh asserts it matches and the release workflow runs it before building. I confirmed it fails on both drift shapes rather than assuming.

engines.node stays ">=22" deliberately. It's the floor npm enforces on consumers, and pointing node-version-file at it is what f95424cc was fixing — a range resolves to the newest release, so ">=22" there silently meant latest.

One thing for your call, in the PR too: Node 26 doesn't reach LTS until October. It's build-time only everywhere except the :browser image, which copies the binary into its runtime stage for Playwright — so that's the one place the major is load-bearing at runtime. 24 is a one-line change to .nvmrc plus the five ARG defaults if you'd rather be on the current LTS; the check script catches a missed one.

---

Generated by Claude Code