Repository navigation
fix(install): recover frontend build from npm optional-deps bug (npm/cli#4828) - #14291
Conversation
…cli#4828) npm ci replays a lockfile resolved on another OS/arch and can skip the platform-specific native binding the bundler needs (e.g. @rolldown/binding-<os>-<arch>), so the cloud/first-run frontend build aborts with 'Cannot find native binding' and the dashboard serves 'Dashboard HTML not found'. Recover in two escalating steps when the build fails: re-resolve dependencies from scratch (re-evaluates optional deps for the current platform), then, if that still omits the binding, install the exact @rolldown/binding-<os>-<arch>[-abi] for the resolved rolldown version. Each step rebuilds; the first that produces a bundle wins. The fast npm ci path is unchanged when it works. Co-authored-by: cykhoo0108 <79309705+cykhoo0108@users.noreply.github.com>
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the recovery's Suggestions
[DESIGN-REVIEWED] 5b79f04 |
Opus 5 Review — ✅ no blocking findingsReviewed Review details
FINDING — install.sh:450 — FINDING — install.sh:472 — [OPUS-REVIEWED] 5b79f04 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
bolichen97
left a comment
There was a problem hiding this comment.
Read the full diff. Required gate PR Readiness green on the current head, no blocking reviews. Approving.
Replaces #4095 by @cykhoo0108
Problem / Motivation
On a fresh cloud launch (and any first-run/dev build) the frontend build can abort with:
install.shbuilds the website withnpm ciwhen apackage-lock.jsonis present.npm cistrictly replays the committed lockfile (resolved on a different OS/arch), so npm's long-standing optional-dependencies bug (npm/cli#4828) drops the platform-specific native binding the bundler (rolldown/vite) needs. The build fails, nowebsite/distis produced, and the gateway serves the "Dashboard HTML not found" page.Why it matters
For a cloud crew the dashboard is the product. The failure is silent from the user's side: the launch "succeeds" (the gateway answers on :5476) but every dashboard load shows "Dashboard HTML not found" with no obvious cause. It reproduces reliably on
linux-arm64(Amazon Linux 2023 arm64 EC2), a common cloud target.What changed (motivation → approach → change)
Symptom:
npm run buildaborts with "Cannot find native binding".Root cause:
npm ci+ [BUG] Platform-specific optional dependencies not being included inpackage-lock.jsonwhen reinstalling withnode_modulespresent npm/cli#4828 → the@rolldown/binding-<os>-<arch>optional dep for the current platform is missing fromnode_modules.Change: keep the fast
npm cipath when it works, but recover on build failure in two escalating steps:node_modulesand re-runnpm install, which re-evaluates optional deps for this platform, then rebuild. The trackedpackage-lock.jsonis left in place, so the working tree stays clean.@rolldown/binding-<os>-<arch>[-abi]matching the resolvedrolldownversion (os/arch fromuname,-gnu/-musldetected vialdd), then rebuild.Each step rebuilds; the first that produces a bundle wins. The common (working)
npm cipath is untouched — the recovery only runs when the build would otherwise fail.Backwards compatibility
Compatible: this only adds a recovery ladder inside the existing frontend-build block of
install.sh; the fastnpm ci+ build path is unchanged when it succeeds, and no contract, flag, or file format is added, renamed, or removed.Tests
No automated test change. The existing installer tests (
test/test_cloud_install.py,test/test_installer_shim_and_cleanup.py) do not assert on the frontend-build block, so they are unaffected.bash -n install.shpasses.Manual verification
This two-step recovery mirrors what resolved the failure on a live
linux-arm64AL2023 EC2 instance during a cloud launch: a clean reinstall re-evaluated the optional deps for arm64, and installing@rolldown/binding-linux-arm64-gnu@<rolldown version>explicitly restored the binding when even that was not enough — after whichnpm run buildproducedwebsite/distand the dashboard rendered. The live arm64 cloud bootstrap cannot be run from CI, so the change is verified by shell-syntax check (bash -n install.sh) plus reproduction of the manual remedy rather than an automated arm64 build.Related Issues
N/A
Pattern harvest
Not generalizable: a one-off recovery for a specific upstream npm bug (npm/cli#4828) in a single install-time build step; there is no reusable rule class here.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)