Skip to content

Reconcile package.json's engines.node floor with the actual runtime requirement #1533

Description

@bloknayrb

Follow-up to #1442, which fixed tandem doctor (and the surrounding docs) to correctly report against package.json's declared "engines": { "node": ">=22.12.0" } floor instead of a stale major-only >= 22 check. That PR deliberately left one question open, because it's a product decision, not a bug fix.

The evidence, gathered while fixing #1442:

  • Every package-lock.json entry whose engines.node mentions 22.12 is a dev: true devDependency — vite (^20.19.0 || >=22.12.0), rolldown and its per-platform @rolldown/binding-* packages (same range), @sveltejs/vite-plugin-svelte (^20.19 || ^22.12 || >=24). All 18 lockfile entries matching 22.12 were independently confirmed dev: true.
  • The highest floor among genuine (non-dev) runtime dependencies entries in the lockfile is >=20.19.0 (dom-serializer).
  • tsup.config.ts's target: "node22" (×3, server/channel/monitor entries) is an esbuild compile target, which means >=22.0.0 — not 22.12.0.
  • Grepping src/ for Node APIs gated behind 22.12 (node:sqlite, fs.glob, styleText, process.features.require_module) returns nothing.
  • npm's engines field is advisory by default (engine-strict off): a mismatch is an EBADENGINE warning, not an install-time block.
  • src/cli/node-version.ts's CLI startup guard (nodeVersionError, gating every tandem/tandem-channel/monitor invocation, including the plugin's) already only enforces >=22.0.0 and was deliberately left that way in Node version floor is stated four ways; tandem doctor passes an install npm refuses #1442 — tightening it to 22.12.0 would have refused Node versions that run Tandem correctly today.

So 22.12.0 is real, but it's a build-toolchain floor (what a contributor's npm install + vite build needs), not the floor Tandem itself needs at runtime once built. package.json's single engines field doesn't distinguish the two, which is arguably one layer up from what #1442's symptom (doctor disagreeing with engines) was actually about.

The open question: should engines.node come down to >=22 (or >=20.19.0, matching the true runtime floor), with 22.12.0 kept as a documented contributor/build-only floor elsewhere (e.g. CONTRIBUTING.md, which already states it separately)? Or is a single conservative number simpler to maintain even though it overstates what's actually required?

Whatever the answer, tests/docs/node-floor-claims.test.ts (added in #1442) pins every prose copy of the floor to MIN_NODE_VERSION in src/cli/doctor.ts, so changing the number is a one-constant edit plus updating that test's expectation — the four docs and the code check can't drift apart silently again either way.

Not urgent — no user-facing bug results from leaving this open (the floor is currently the more conservative side of "safe").

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions