engines admits Node versions the pinned pnpm@11 cannot run on (node:sqlite), so an engines-compliant checkout dies before install
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:
- Node 20.18.0 —
corepack pnpmvia a stale shim:ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING(corepack relic; #167 territory). - Node 20.18.0 —
npm i -g pnpm@11 && pnpm install:ERR_UNKNOWN_BUILTIN_MODULEfrom pnpm's own bundle (nonode:sqlitein 20.x). Engines says >=22, fair — but the error names nothing actionable. - Node 23.3.0 (satisfies
>=22) —npx pnpm@11 install:ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqliteat../store/index/lib/index.js. Engines-compliant Node, pinned pnpm, cold stop. - 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.nodeto the actual floor pnpm 11 needs (the first release line with unflaggednode:sqlite— e.g.>=22.13), or document the floor in CONTRIBUTING next to the corepack note from #167. - Optionally a preflight in
package.jsonpreinstallor 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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