A Braid-built Node project won't start on a Mac: its lockfile lacks the Mac binaries #273

Closed
opened 2026-10-28 11:54:57 -04:00 by cmoriarty · 2 comments
Owner

What happens
The lockfiles of pinball-braid-2 and pinball-braid-solo, written in Braid's Linux container, list only the Linux build of Vite's bundler. On a Mac, npm install then npm run dev fails with Cannot find module '@rolldown/binding-darwin-…' until that package is added by hand.

Fix

  • When a run writes or updates package-lock.json, make it hold every platform's optional native packages (or regenerate it with no node_modules), so it installs anywhere.
  • A self-check that installs a sample project's lockfile for another platform would catch it.

Done when
A Node project Braid built starts with npm install && npm run dev on macOS and Linux.

From the #260 hands-on play.

**What happens** The lockfiles of `pinball-braid-2` and `pinball-braid-solo`, written in Braid's Linux container, list only the Linux build of Vite's bundler. On a Mac, `npm install` then `npm run dev` fails with `Cannot find module '@rolldown/binding-darwin-…'` until that package is added by hand. **Fix** - When a run writes or updates `package-lock.json`, make it hold every platform's optional native packages (or regenerate it with no `node_modules`), so it installs anywhere. - A self-check that installs a sample project's lockfile for another platform would catch it. **Done when** A Node project Braid built starts with `npm install && npm run dev` on macOS and Linux. _From the #260 hands-on play._
Author
Owner

Braid's own console has it too. In a fresh worktree on a Mac, npm ci in ui/ installs no Mac build of rolldown, and vitest stops with Cannot find native binding. npm install --no-save @rolldown/binding-darwin-arm64@<version> works around it. The fix should cover ui/package-lock.json as well as the lockfiles runs write.

**Braid's own console has it too.** In a fresh worktree on a Mac, `npm ci` in `ui/` installs no Mac build of `rolldown`, and `vitest` stops with `Cannot find native binding`. `npm install --no-save @rolldown/binding-darwin-arm64@<version>` works around it. The fix should cover `ui/package-lock.json` as well as the lockfiles runs write.
Author
Owner

Shipped in #301 (5355515, deployed). It's part of planned-projects-finish-right.

The cause was not the lockfile. pinball-braid-2's and pinball-braid-solo's lockfiles list every platform's rolldown binding, with integrity hashes. The Mac's default Node, nvm's 20.18.0, is below Vite 8's ^20.19.0 || >=22.12.0, and npm skips an optional native package whose engine doesn't match, without saying so. Installed with Node 22, the same lockfile brings the Mac binding.

Fix: a new Node project gets .nvmrc (the Node Braid built it with) and an .npmrc with engine-strict=true, written beside the .gitignore. Runs install with npm_config_engine_strict=false, so a run never fails on a dependency's range. Braid's own ui/ has .nvmrc (22) and the same .npmrc.

Seen with run 139's game (cmoriarty/breakout-planned), cloned to this Mac:

  • The proposal's .gitignore step printed "and .nvmrc and .npmrc for Node". The repository has .nvmrc 26 and .npmrc engine-strict=true.
  • With Node 20.18, npm install now stops: Unsupported engine … Required: {"node":">=22.12.0"} Actual: {"node":"v20.18.0"}. The old failure was a missing binding at npm run dev.
  • With Node 22.22.3: npm install, then npm run dev. Vite is ready in 486 ms and serves the game: title "Breakout", its canvas, and /src/main.js answers 200.

nvm alias default 22 would make Node 22 this Mac's default.

Shipped in #301 (5355515, deployed). It's part of `planned-projects-finish-right`. **The cause was not the lockfile.** pinball-braid-2's and pinball-braid-solo's lockfiles list every platform's rolldown binding, with integrity hashes. The Mac's default Node, nvm's 20.18.0, is below Vite 8's `^20.19.0 || >=22.12.0`, and npm skips an optional native package whose engine doesn't match, without saying so. Installed with Node 22, the same lockfile brings the Mac binding. **Fix:** a new Node project gets `.nvmrc` (the Node Braid built it with) and an `.npmrc` with `engine-strict=true`, written beside the `.gitignore`. Runs install with `npm_config_engine_strict=false`, so a run never fails on a dependency's range. Braid's own `ui/` has `.nvmrc` (22) and the same `.npmrc`. **Seen with run 139's game (cmoriarty/breakout-planned), cloned to this Mac:** - The proposal's `.gitignore` step printed "and .nvmrc and .npmrc for Node". The repository has `.nvmrc` `26` and `.npmrc` `engine-strict=true`. - With Node 20.18, `npm install` now stops: `Unsupported engine … Required: {"node":">=22.12.0"} Actual: {"node":"v20.18.0"}`. The old failure was a missing binding at `npm run dev`. - With Node 22.22.3: `npm install`, then `npm run dev`. Vite is ready in 486 ms and serves the game: title "Breakout", its canvas, and `/src/main.js` answers 200. `nvm alias default 22` would make Node 22 this Mac's default.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#273
No description provided.