OctoLauncher-personal/BUILD.md

OctoLauncher Build Guide (Windows)

End-to-end setup that gets npm run dev and npm run dist working on a fresh Windows machine. Captured from a working build on Windows 10 / April 2026.

Changes made to the dev environment

The project as checked out does not build on a default up-to-date Windows dev machine. These are the deltas applied to get it working, in order:

1. Added a Node version manager (fnm) and installed Node 20 alongside the existing Node 24. Node 24 was the system default and caused nan / dll-inject compile failures. Node 20 is now the fnm default but Node 24 is still available via fnm use system.
2. Installed Visual Studio 2022 Build Tools with the VCTools workload and Windows 11 SDK. Machine already had VS2026 (v18), but node-gyp v10 (shipped with Node 20's npm) doesn't detect it. VS2022 now lives side-by-side under C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools.
3. Unset ELECTRON_RUN_AS_NODE per-shell before launching Electron. This var is set globally by VSCode's integrated terminal (inherited from the extension host): it is not something we can remove permanently without breaking VSCode. It has to be unset in each shell that runs npm run dev / dist.
4. Populated node_modules in both main/ and main/server/. The tree was checked in empty.

Nothing in the repo itself was modified; all fixes were environmental. If another developer checks this repo out, they need to apply items 1-4 on their own machine. The sections below are that recipe.

---

Prerequisites

1. Node.js 20 (not 22, not 24)

Node 24 breaks the dll-inject native module; its nan C++ bindings don't compile against V8 in Node 22+. Stick to Node 20 LTS.

Install via fnm so you can keep your system Node separate:

winget install Schniz.fnm --accept-source-agreements --accept-package-agreements
fnm install 20
fnm default 20

Verify: node -v should print v20.x.x.

2. Visual Studio 2022 Build Tools (C++ workload)

dll-inject and stormlib-node compile native addons via node-gyp. node-gyp v10 (bundled with Node 20's npm) only recognizes VS2017-2022; newer VS versions (2026 / v18) are not detected.

winget install Microsoft.VisualStudio.2022.BuildTools \
  --accept-source-agreements --accept-package-agreements \
  --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows11SDK.22621 --includeRecommended"

~6 GB download, requires admin. Even if you already have VS2026, you need VS2022 side-by-side for node-gyp.

3. Python 3 (usually already present)

node-gyp needs Python on PATH. Any 3.x works.

Install dependencies

From the repo root:

npm install --ignore-scripts
node node_modules/electron/install.js
node_modules/.bin/electron-builder.cmd install-app-deps

Why the three-step approach: dll-inject requires ClangCL if compiled against the system Node, but compiles fine against Electron's bundled V8 headers (which electron-builder install-app-deps uses). Running plain npm install fails if your VS2022 installation doesn't include the LLVM/ClangCL component; --ignore-scripts skips that step and lets install-app-deps handle it correctly.

Or, use the provided build script which downloads a portable Node 20 and handles everything automatically:

.\Tools\launcher\install.ps1

Then the server (only needed if running a local CDN, see server/.env.example):

cd server
npm install
cd ..

Critical env var: ELECTRON_RUN_AS_NODE

VSCode's integrated terminal sets ELECTRON_RUN_AS_NODE=1 (inherited from VSCode's extension host). This makes Electron binaries launch as plain Node, so require('electron') returns a path string instead of the API: the app crashes with TypeError: Cannot read properties of undefined (reading 'isPackaged').

Before any npm run dev / npm run build / npm run dist:

unset ELECTRON_RUN_AS_NODE 

Remove-Item Env:ELECTRON_RUN_AS_NODE

An external terminal (Windows Terminal, cmd, plain PowerShell) doesn't have this problem; the variable is only set inside VSCode.

Running in dev

npm run dev

Starts electron-vite, builds main + preload + renderer, opens an Electron window on http://localhost:5173 (or 5174 if 5173 is taken). Closing the window ends the session.

You'll see benign warnings in the console:

• ERROR:cache_util_win.cc ... Access is denied: OneDrive sync locking Electron's user-data cache. Cosmetic. To silence, move the project out of OneDrive or set a custom user-data dir.
• Browserslist: caniuse-lite is outdated: cosmetic.

Building for distribution

The dist script runs tsc && npm run build && npm run pack:

unset ELECTRON_RUN_AS_NODE
npm run dist

Outputs land in dist/:

• OctoLauncher.exe: portable single-file build
• OctoLauncher_Installer.exe: NSIS installer

Targets are configured in electron-builder.yml.

Before publishing

• The build uses .env.production (committed) which already points to https://octowow.st: no .env file needed for production builds.
• Code signing is not configured. Unsigned Windows builds trigger SmartScreen warnings. To sign, add a win.certificateFile + password (or use env-based signing) to the electron-builder config.

Troubleshooting

Symptom	Cause	Fix
nan_scriptorigin.h ... cannot convert 'v8::Isolate *' during npm install	Node 22+ breaks nan	Switch to Node 20
gyp ERR! find VS Could not find any Visual Studio installation	Only VS2023+ installed	Install VS2022 Build Tools
error MSB8020: The build tools for ClangCL cannot be found	Missing LLVM component during plain npm install	Use npm install --ignore-scripts + electron-builder install-app-deps (see above)
TypeError: Cannot read properties of undefined (reading 'isPackaged') at launch	ELECTRON_RUN_AS_NODE=1 set by VSCode	unset ELECTRON_RUN_AS_NODE
Port 5173 is in use	Prior dev server didn't exit cleanly	Ignore (vite falls back to 5174) or kill the stale process