theam / theam/facility

engines admits Node versions the pinned pnpm@11 cannot run on (node:sqlite), so an engines-compliant checkout dies before install

Open Beginner friendly
#240 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
71
Forks
64
Avg merge
15h 38m
Merged PRs (30d)
66

Description

Summary

package.json declares "engines": { "node": ">=22" } and pins "packageManager": "pnpm@11.20.0" — but pnpm 11 hard-requires the node:sqlite builtin, which is flag-gated until late in the Node 22/23 lines. The engines range therefore admits a band of Node versions on which the pinned package manager cannot start at all, and the contributor sees a pnpm stack trace rather than anything naming the real constraint. Windows contributors, who tend to sit on nvm-windows-installed even-numbered releases, walk straight into it.

Adjacent to #167 (corepack missing on Node 25+ breaks the documented quickstart) but a different clause: #167 is about how pnpm gets installed; this is about engines promising Node versions the pinned pnpm cannot run on.

Observed ladder (Windows 11, nvm-windows, clean checkout of main)

Every rung verbatim, same repo, same day:

  1. Node 20.18.0corepack pnpm via a stale shim: ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING (corepack relic; #167 territory).
  2. Node 20.18.0npm i -g pnpm@11 && pnpm install: ERR_UNKNOWN_BUILTIN_MODULE from pnpm's own bundle (no node:sqlite in 20.x). Engines says >=22, fair — but the error names nothing actionable.
  3. Node 23.3.0 (satisfies >=22) — npx pnpm@11 install: ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite at ../store/index/lib/index.js. Engines-compliant Node, pinned pnpm, cold stop.
  4. Node 22.23.2 (WSL, same machine): everything works — which is the point: the working floor is a late 22.x, not ">=22".

Why it matters

The method doc's own thesis is that agents (and people) hedge when "the environment can't run anything." A first-touch contributor on an engines-compliant Node gets a pnpm internals stack trace before reaching pnpm install's first byte of output. Nothing in README, CONTRIBUTING, or the error path names node:sqlite or the real minimum.

Suggested fix (small)

  • Raise engines.node to the actual floor pnpm 11 needs (the first release line with unflagged node:sqlite — e.g. >=22.13), or document the floor in CONTRIBUTING next to the corepack note from #167.
  • Optionally a preflight in package.json preinstall or the quickstart: node -e "require('node:sqlite')" with a one-line human message when it throws.

Happy to send the PR for whichever shape you prefer — it pairs naturally with the #167 quickstart correction.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with package.json and the Node and package-manager requirements described in the issue, then check the related setup guidance in README and CONTRIBUTING, including the note from #167. Verify the chosen fix against the reported Node versions and confirm that an engines-compliant checkout reaches a useful install error or completes installation.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js
Domain
build-system, developer-experience
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.