plans/managed-node.md
Node.js setup is the single largest onboarding failure cluster in the issue tracker (~36 issues). Recurring root causes:
~/.local shims (#1403), wrong node found first (Brackets' bundled v6, #2953).reloadNodePath() on Windows runs cmd /c echo %PATH%, which only echoes the inherited PATH and can never see what an installer just added (#1236, #3665, #1450, #970).spawn(..., {shell: true}) entirely — one bad entry fails every detection command with ENOENT and the UI spins forever (#3612, #1536, #2).| Decision | Choice |
|---|---|
| Delivery | Download on demand (official ~30 MB archive, checksum-verified, mirror fallback) — not bundled in the installer |
| Precedence | User choice in settings, default system-first (managed fills the gap when system Node is missing/unhealthy/too old) |
| Install trigger | Explicit button only — nothing downloads without a click |
| Platforms (v1) | Windows + macOS; Linux keeps the current flow (glibc/musl headaches deferred) |
Pinned version: v22.22.3 — matches the URL getNodeDownloadUrl() already points users at, so UI/docs stay consistent.
src/ipc/utils/managed_node.tsMirrors the managed-pnpm pattern (#3734) in socket_firewall.ts. Extract the shared pieces (prependPathSegment, managed-tools dir helpers) into a managed_tools.ts.
{ version, platform/arch → { url, sha256 } }, sha256 taken from nodejs.org's SHASUMS256.txt and committed. Vendored hashes mean the mirror can't tamper: primary https://nodejs.org/dist/..., fallback https://registry.npmmirror.com/-/binary/node/... (nodejs.org is unreliable from China; we have Chinese-language users, e.g. #3705).node-v22.22.3-win-{x64,arm64}.zip; macOS node-v22.22.3-darwin-{arm64,x64}.tar.gz (tar.gz, not tar.xz — avoids an xz dependency).net (inherits system/corporate proxy config) into userData/managed-tools/node/tmp/, with retry and IPC progress events.shell: false with --version → rename to userData/managed-tools/node/v22.22.3/. The post-extract spawn is the antivirus canary: if AV quarantined node.exe (AV already flags Dyad binaries — #1253, #861), fail with a targeted "your antivirus may have blocked it" error, not a mystery.managedPnpmInstallPromise) so double-clicks / concurrent status checks don't race.src/lib/schemas.ts next to customNodePath: nodeRuntimePreference: "system" | "managed", default "system".reloadNodePath() (src/ipc/handlers/node_handlers.ts):
customNodePath — an explicit manual path always wins (most deliberate signal)"managed" → managed bin dir prepended"system" → system Node if healthy (spawns successfully and version ≥ 20 floor — catches the v6/v14 cases); otherwise fall back to managed if installedprependPathSegment into process.env.PATH and getPackageManagerCommandEnv(), so app_runtime_service.ts (app spawns) and the managed-pnpm installer pick it up with no changes.npm install ...; with managed Node first on PATH, that npm is managed Node's npm, and node pnpm.cjs runs under managed Node. Managed Node + managed pnpm = zero external environment dependencies. Sequencing matters: Node install must complete before triggering the pnpm install, or pnpm keeps failing against the broken system env.systemContracts (src/ipc/types/system.ts)getNodejsStatus gains: source: "system" | "managed" | "custom", resolved nodePath, managedNodeInstalled, managedNodeVersion, and systemNodeTooOld (distinct UI message vs. missing).installManagedNode handler + progress event channel; removeManagedNode for settings.src/components/preview_panel/PreviewPanel.tsx, the #3738 redesign): primary button becomes "Install Node.js for me (~30 MB)" with a progress bar. Secondary links: "Download from nodejs.org instead" (current handleInstallNode behavior) and "I already have Node.js installed…" → existing NodePathSelector./opt/homebrew/bin/node)"), the preference toggle, and "Remove managed Node.js" (deletes the dir, flips preference back to system). Full transparency defuses the "what did you install on my machine" objection.userData/managed-tools; if not, add it (don't orphan ~150 MB).| Case | Handling |
|---|---|
| Offline / download fails | Distinct error state with "download manually from nodejs.org" fallback; never a hanging spinner (the #2/#3612 lesson) |
| Checksum mismatch (corporate TLS interception, truncation) | Delete temp, retry once on mirror, then error naming the cause |
| Disk full mid-extract | Temp dir + atomic rename — no half-installed runtime ever lands on PATH |
AV deletes/blocks extracted node.exe | Post-extract spawn check fails → targeted error + docs link + telemetry |
| Corrupted system PATH (#3612-style ENOENT) | All managed-runtime operations spawn absolute paths with shell: false. Caveat: app dev-servers still run through a shell, so also sanitize the child env by dropping PATH entries that don't exist — this is the piece that actually closes category 4 |
| Spaces in Windows profile path (#3513) | Managed dir lives under %APPDATA% (commonly contains spaces) — the no-shell absolute-path rule covers install/verify; add an E2E with a spaced app path |
| Rosetta (x64 Dyad on arm64 Mac) | Match the app's arch (os.arch()); x64 Node under Rosetta works. No sysctl sniffing in v1 |
| System Node disappears mid-session (nvm switch, uninstall) | Status re-check on window focus; runtime resolution happens per-spawn via env building, so the next run falls back per precedence |
| Preference set to "managed" but not installed | Toggle triggers the install prompt; resolution treats not-installed managed as absent and falls back to system with a warning banner |
IS_TEST_BUILD serves a tiny fixture archive from a local server (exercises the real download/verify/extract machinery with a fake payload). Specs:
managed_node_install started/succeeded/failed with failure category (network / checksum / extract / av-blocked / disk), plus runtime_source on app start — measures whether this kills the failure categories and informs whether to later relax "explicit button only" toward auto-install.
reloadNodePath()'s cmd /c echo %PATH% can never see registry PATH changes made after launch; re-read machine+user Path from the registry instead. https://github.com/dyad-sh/dyad/pull/3742managed_node.ts + IPC + resolution wiring + settings field (no UI; dev-flag testable via a DYAD_DEV_NODEJS_STATUS-style override)