Skip to content

fix(install): recover frontend build from npm optional-deps bug (npm/cli#4828) - #14291

Merged
bolichen97 merged 1 commit into
mainfrom
drive/4095-npm-optional-deps
Sep 26, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
drive/4095-npm-optional-deps

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Replaces #4095 by @cykhoo0108

Problem / Motivation

On a fresh cloud launch (and any first-run/dev build) the frontend build can abort with:

Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828).
... Cannot find module '@rolldown/binding-linux-arm64-gnu'

install.sh builds the website with npm ci when a package-lock.json is present. npm ci strictly 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, no website/dist is 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 build aborts with "Cannot find native binding".

  • Root cause: npm ci + [BUG] Platform-specific optional dependencies not being included in package-lock.json when reinstalling with node_modules present npm/cli#4828 → the @rolldown/binding-<os>-<arch> optional dep for the current platform is missing from node_modules.

  • Change: keep the fast npm ci path when it works, but recover on build failure in two escalating steps:

    1. Remove node_modules and re-run npm install, which re-evaluates optional deps for this platform, then rebuild. The tracked package-lock.json is left in place, so the working tree stays clean.
    2. If the binding is still missing, install the exact @rolldown/binding-<os>-<arch>[-abi] matching the resolved rolldown version (os/arch from uname, -gnu/-musl detected via ldd), then rebuild.

    Each step rebuilds; the first that produces a bundle wins. The common (working) npm ci path 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 fast npm 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.sh passes.

Manual verification

This two-step recovery mirrors what resolved the failure on a live linux-arm64 AL2023 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 which npm run build produced website/dist and 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality (no new functionality; installer tests unaffected)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A
  • No secrets, credentials, or internal references in the diff

…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>
@iamwhatever
iamwhatever requested review from a team and bolichen97 September 26, 2026 21:37
@iamwhatever iamwhatever added the drive-to-green PR claimed by drive-to-green pipeline label Sep 26, 2026
@iamwhatever iamwhatever self-assigned this Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 5b79f04e313c35a106fe422f69a1d01772a621fa and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5b79f04

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5b79f04e313c35a106fe422f69a1d01772a621fa: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 5b79f04e313c35a106fe422f69a1d01772a621fa — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the recovery's npm install cannot rewrite tracked package-lock.json — a dirtied lockfile breaks the advertised git pull && bash install.sh update path later.

Suggestions

  • Gate the rm -rf node_modules step on the build log containing "Cannot find native binding": today any genuine build error (real TS/vite failure) pays two extra installs and three builds before surfacing, and the wipe can mutate the lockfile for failures the ladder can't fix.
  • After the recovery install, restore the lockfile explicitly (git checkout -- package-lock.json or --no-package-lock on the recovery install) so "the working tree stays clean" is guaranteed rather than assumed.

[DESIGN-REVIEWED] 5b79f04

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 5b79f04e313c35a106fe422f69a1d01772a621fa — this comment is updated in place on each push.

Review details

set -o pipefail inverts the new musl probe, so the last-resort binding repair installs the glibc binding on Alpine — advisory, nothing blocks.

FINDING — install.sh:450 — if ldd --version 2>&1 | grep -qi musl runs under the script's set -euo pipefail (install.sh:24, inherited by the subshell and function); musl's ldd prints its musl libc (…) banner plus a Usage: line to stderr and exits non-zero, so pipefail makes the pipeline non-zero even though grep matched → _rd_abi="-gnu" → line 456 installs @rolldown/binding-linux-x64-gnu (its lockfile entry declares only os/cpu, no libc, so npm installs it happily), rolldown's napi loader still wants -musl, and the escalation step added for exactly this case leaves the build failing → Fix: neutralise pipefail for the probe, e.g. if { ldd --version 2>&1 || true; } | grep -qi musl; then.

FINDING — install.sh:472 — if ! _fe_build fires the recovery on any non-zero build, with no test of $_fe_log for "Cannot find native binding", so the V8 OOM this same block's comment describes (or a tsc -p tsconfig.app.json error) now runs rm -rf node_modules + a full npm install + two more builds before reporting the same failure, and because that npm install is a plain command inside the then list, errexit aborts the subshell on a transient registry error and leaves website/node_modules deleted where the old npm ci && npm run build chain left it intact → Fix: gate the escalation on the symptom, e.g. if ! _fe_build; then if grep -q "Cannot find native binding\|@rolldown/binding" "$_fe_log"; then …, and try the cheap _fe_install_binding before the destructive reinstall.

[OPUS-REVIEWED] 5b79f04

Verdict parsed from the review's SHA-scoped output markers for commit 5b79f04e313c35a106fe422f69a1d01772a621fa.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5b79f04e313c35a106fe422f69a1d01772a621fa: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 26, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the full diff. Required gate PR Readiness green on the current head, no blocking reviews. Approving.

@bolichen97
bolichen97 enabled auto-merge (squash) September 26, 2026 22:55
@bolichen97
bolichen97 merged commit 705b5a9 into main Sep 26, 2026
102 of 116 checks passed
@bolichen97
bolichen97 deleted the drive/4095-npm-optional-deps branch September 26, 2026 22:55
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 26, 2026
@NicholasRBowers NicholasRBowers removed the drive-to-green PR claimed by drive-to-green pipeline label Sep 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants