From 3790c00363098be32b9ab78f29686ae1d82c568b Mon Sep 17 00:00:00 2001 From: Yuhao Chen Date: Tue, 12 May 2026 16:17:44 +0800 Subject: [PATCH] docs: add Windows troubleshooting guide (#478) (#1170) * docs: add Windows troubleshooting guide (#478) Add docs/windows-troubleshooting.md with step-by-step fixes for the most common native-Windows setup errors: - Node 24 / nvm-windows gotchas (fake nvm file in System32) - pnpm not found after installation - Build scripts blocked by pnpm 10 (better-sqlite3, sharp) - Visual Studio / gyp build errors - Starting the dev server - Optional OpenCode CLI setup Also update CONTRIBUTING.md and QUICKSTART.md to link to the new guide instead of the vague "file an issue if it doesn't" note. * docs: fix Windows guide command accuracy (#1170) Address all 6 inline review comments from lefarcen: - Pin npm-global pnpm install to @10.33.2 (matches packageManager field) - Use where.exe instead of bare where (PowerShell alias conflict) - Fix OpenCode package: opencode-ai (not opencode), binary is opencode - Add EPERM fallback note for corepack enable on protected installs - Add Python check for gyp ERR! find Python - Expand diagnostic checklist with corepack, python, execution policy Also remove redundant corepack pnpm --version from checklist. --- CONTRIBUTING.md | 2 +- QUICKSTART.md | 2 +- docs/windows-troubleshooting.md | 218 ++++++++++++++++++++++++++++++++ 3 files changed, 220 insertions(+), 2 deletions(-) create mode 100644 docs/windows-troubleshooting.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54d985923..5ed578043 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ pnpm typecheck # tsc -b --noEmit pnpm --filter @open-design/web build # web package build when needed ``` -Node `~24` and pnpm `10.33.x` are required. `nvm` / `fnm` are optional; use `nvm install 24 && nvm use 24` or `fnm install 24 && fnm use 24` if you prefer managing Node that way. macOS, Linux, and WSL2 are the primary paths. Windows native should work but isn't a primary target — file an issue if it doesn't. +Node `~24` and pnpm `10.33.x` are required. `nvm` / `fnm` are optional; use `nvm install 24 && nvm use 24` or `fnm install 24 && fnm use 24` if you prefer managing Node that way. macOS, Linux, and WSL2 are the primary paths. Windows native is supported; see [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md) for the common setup gotchas. ## Docker Setup diff --git a/QUICKSTART.md b/QUICKSTART.md index 7af7c9d91..23f20c119 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -8,7 +8,7 @@ Run the full product locally. - **Node.js:** `~24` (Node 24.x). The repo enforces this through `package.json#engines`. - **pnpm:** `10.33.x`. The repo pins `pnpm@10.33.2` through `packageManager`; use Corepack so the pinned version is selected automatically. -- **OS:** macOS, Linux, and WSL2 are the primary paths. Windows native should work for most flows, but WSL2 is the safer baseline. +- **OS:** macOS, Linux, and WSL2 are the primary paths. Windows native is supported; see [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md) for common setup gotchas. - **Optional local agent CLI:** Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen, Qoder CLI, GitHub Copilot CLI, etc. If none are installed, use the BYOK API mode from Settings. ### Local agent CLI and PATH diff --git a/docs/windows-troubleshooting.md b/docs/windows-troubleshooting.md new file mode 100644 index 000000000..b24ea19d1 --- /dev/null +++ b/docs/windows-troubleshooting.md @@ -0,0 +1,218 @@ +# Windows Troubleshooting Guide + +Open Design runs on Windows natively, but the path is less travelled than macOS, Linux, or WSL2. This guide covers the most common errors you will hit on a fresh Windows machine and the exact fix for each. + +> **Tip:** If you already have WSL2 set up, that is the smoothest path on Windows. This guide is for native Windows (PowerShell). + +--- + +## Prerequisites + +| Tool | Version | How to verify | +|---|---|---| +| Node.js | `~24` | `node -v` | +| pnpm | `10.33.x` | `pnpm -v` | +| Git | any recent | `git --version` | + +--- + +## 1. Node 24 installation + +### Symptom +`node -v` returns something older than `v24.x.x`, or you do not have Node installed at all. + +### Fix + +**Option A — nvm-windows (recommended)** + +1. Install [nvm-windows](https://github.com/coreybutler/nvm-windows/releases). +2. In a fresh PowerShell window: + + ```powershell + nvm install 24 + nvm use 24 + node -v # should print v24.x.x + ``` + +**Option B — Official installer** + +Download and run the Node 24 `.msi` from [nodejs.org](https://nodejs.org/). + +### Common nvm-windows gotcha + +If running `nvm version` or `node -v` pops up a Windows dialog that asks *"How do you want to open this file?"*, a fake `nvm` file (no extension) has been created in `C:\Windows\System32`. + +**Fix:** Delete that file, then restart PowerShell. + +--- + +## 2. pnpm not found + +### Symptom + +```text +pnpm : The term 'pnpm' is not recognized as the name of a cmdlet... +``` + +### Fix (Corepack — recommended) + +The repo pins `pnpm@10.33.2` in `packageManager`. Corepack selects that exact version automatically: + +```powershell +corepack enable +corepack pnpm --version # should print 10.33.2 +``` + +> **Note:** If `corepack enable` fails with `EPERM` or `EACCES` (common when Node is installed under `C:\Program Files\nodejs`), use the npm-global fallback in the next section instead. + + + +### Fix (npm global — alternative) + +If Corepack is not available: + +```powershell +npm install -g pnpm@10.33.2 +pnpm -v # should print 10.33.2 +``` + +--- + +## 3. Build scripts blocked + +### Symptom + +During `pnpm install` you see: + +```text +Ignored build scripts: better-sqlite3, ... +``` + +Later, `pnpm tools-dev run web` fails with native-module errors. + +### Fix + +pnpm 10 blocks lifecycle scripts by default. Allow the packages that need native compilation: + +```powershell +pnpm approve-builds +``` + +Approve any packages that appear in the list (commonly `better-sqlite3`, `electron`, and `esbuild`). Then re-run: + +```powershell +pnpm install +``` + +> **Note:** `better-sqlite3` may fall back to compiling from source on Windows. If `pnpm install` hangs or fails on this package, make sure the Visual Studio Build Tools (step 4) are installed *before* running `pnpm install`. + +--- + +## 4. Visual Studio / `gyp` build errors + +### Symptom + +```text +gyp ERR! find VS could not find Visual Studio +``` + +or + +```text +error MSB8036: The Windows SDK version was not found +``` + +### Fix + +Install **Build Tools for Visual Studio 2022** with the following workloads: + +- **Desktop development with C++** +- **MSVC v143 - VS 2022 C++ x64/x86 build tools** +- **Windows 11 SDK** (or Windows 10 SDK if you are on Windows 10) + +Download: [https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) + +If you see `gyp ERR! find Python`, verify Python is installed: + +```powershell +python --version # or py --version +``` + +If missing, install Python 3.x from [python.org](https://www.python.org/downloads/) and ensure it's on PATH. + +After installing all build tools, open a **fresh** PowerShell window and re-run `pnpm install`. + +--- + +## 5. PowerShell execution policy + +### Symptom + +```text + cannot be loaded because running scripts is disabled on this system. +``` + +### Fix + +On fresh Windows installs, PowerShell blocks script execution by default: + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + +Restart PowerShell after changing the policy. + +--- + +## 6. Start the dev server + +### Symptom +You have completed the steps above but are not sure how to launch the app. + +### Fix + +From the repository root: + +```powershell +pnpm tools-dev run web +``` + +Expected output ends with something like: + +```text +Open Design dev server ready + - Local: http://localhost:17573 +``` + +The exact port may change; always read the terminal output. + +--- + +## Quick diagnostic checklist + +Run these commands in PowerShell before opening an issue. Include the output in your report. + +```powershell +node -v +pnpm -v +where.exe pnpm +where.exe node +where.exe opencode +corepack --version +python --version # or py --version +Get-ExecutionPolicy -List +``` + +--- + +## Optional: OpenCode agent CLI on Windows + +OpenCode is one of the local agent CLIs Open Design can drive. If you want to use it: + +```powershell +npm install -g opencode-ai +where.exe opencode # should show C:\Users\YOUR_USERNAME\AppData\Roaming\npm\opencode.cmd +opencode --version +``` + +If Open Design still shows OpenCode as *not installed* in **Settings → Execution & model**, click **Rescan** after confirming the `opencode.cmd` directory is on your user `PATH`.