diff --git a/skills/devops/electron-build/SKILL.md b/skills/devops/electron-build/SKILL.md new file mode 100644 index 0000000..0fed65f --- /dev/null +++ b/skills/devops/electron-build/SKILL.md @@ -0,0 +1,136 @@ +--- +name: electron-build +description: "Electron desktop app builds: cross-compile for Windows on Linux and fix bundled Chromium DLL issues." +version: 1.0.0 +author: Hermes Agent +license: MIT +metadata: + hermes: + tags: [electron, windows, cross-compile, nsis, exe, msi, wine, chromium, dll-fix, build] + related_skills: [hermes-desktop-build] +--- + +# Electron Build + +Two build/deploy concerns for Electron desktop apps: cross-compiling for Windows from Linux, and fixing bundled Chromium DLL issues on Windows. + +## Section 1: Cross-Compile Linux → Windows + +Build Windows exe/msi/installer from an Electron project on a Linux host. + +**When to use:** Building Electron apps for Windows users from a Linux CI/CD server. + +### Prerequisites + +- Node.js 18+ and npm +- Disk space: **at least 300MB free** per build (electron binary ~115MB + app + NSIS output ~160MB) +- `wine` for NSIS installer signing step (even without a certificate, makensis needs wine) + +### Install Wine + +```bash +sudo dpkg --add-architecture i386 +sudo apt-get update +sudo apt-get install -y wine32:i386 wine64 +``` + +### Disable Code Signing (no certificate) + +```json +"win": { + "target": ["nsis", "portable"], + "icon": "assets/icon.ico", + "signAndEditExecutable": false, + "sign": null +} +``` + +### Build + +```bash +npm run build:win +# Output: dist/*.exe, dist/*.msi +``` + +### Full Build-to-Deploy Workflow (AtomK Desktop) + +```bash +# 1. Version bump → branch → PR → merge (Gitea main is protected) +cd /path/to/project +npm version 3.9.XX --no-git-tag-version +git checkout -b release/v3.9.XX +git add package.json && git commit -m "build: bump version to 3.9.XX" +git push origin release/v3.9.XX + +# 2. Create PR + merge via Gitea API (basic auth, token unreliable) +python3 -c " +import requests, base64 +auth = base64.b64encode(b'USER:PASS').decode() +r = requests.post('https://gitea.HOST/api/v1/repos/OWNER/REPO/pulls', + headers={'Authorization': f'Basic {auth}', 'Content-Type': 'application/json'}, + json={'title':'build: bump to X.XX','head':'release/v3.9.XX','base':'main'}, verify=False) +pr = r.json()['number'] +requests.post(f'.../pulls/{pr}/merge', headers={'Authorization': f'Basic {auth}'}, json={'Do':'merge'}, verify=False) +" + +# 3. Pull main + build +git checkout main && git pull origin main +rm -rf dist/ +NODE_OPTIONS=--max-old-space-size=4096 npm run build:win + +# 4. Upload to Tencent COS (Hong Kong region) +source ~/.hermes/custom_services.env +coscmd -b 9websclub-1251422183 -r ap-hongkong upload dist/*.exe desktop/ +coscmd -b 9websclub-1251422183 -r ap-hongkong upload dist/*.exe.blockmap desktop/ + +# 5. Clean up +git branch -d release/v3.9.XX +git push origin --delete release/v3.9.XX +``` + +### Key Pitfalls + +1. **Disk space** — 300MB+ per build; clean old builds before new ones +2. **Wine warnings** — wine32 display driver warnings are harmless for CLI usage +3. **COS upload** — use `coscmd` for Tencent Cloud (configured via `~/.hermes/custom_services.env`), `aws s3` for AWS +4. **Code signing** — without a certificate, set `signAndEditExecutable: false` and `sign: null` +5. **Gitea protected branches** — `main` is usually protected; push to `release/vX.X.XX` branch instead, then create + merge PR via Gitea API. Use basic auth (username:password base64) — token may be expired. + +**See:** `references/electron-cross-compile.md` for full step-by-step, NSIS config, and upload procedures. + +## Section 2: Bundled Chromium DLL Fix on Windows + +When bundling Chromium inside an Electron app for CDP/browser automation, 3 GPU DLLs must be present or Chromium crashes silently on Windows. + +### Problem + +Electron apps bundling Chromium fail silently with no error output. Root cause: GPU-related DLLs were removed to reduce installer size, but Chromium requires them even with `--disable-gpu`. + +### Missing DLLs + +Copy these from a matching Chromium for Windows release: +- `D3DCompiler_47.dll` (~4.9MB) +- `libEGL.dll` (~494KB) +- `libGLESv2.dll` (~8.2MB) + +Source: `https://storage.googleapis.com/chromium-browser-snapshots/Win//chrome-win.zip` + +### Key Insight + +**`--disable-gpu` is NOT sufficient.** Chromium still loads these DLLs at startup for basic rendering pipeline initialization. + +### Fix Steps + +1. Download matching Chromium version full archive +2. Copy 3 DLLs to bundled chromium directory (e.g., `resources/chromium/`) +3. Remove `--disable-gpu` flag from spawn args (now GPU works properly) +4. Add `diagnoseBrowserSearch()` function: check registry paths, known paths, DLL presence +5. Rebuild: `npm run build:win` + +### Verification + +```bash +7z l dist/app-X.X.X-setup.exe | grep -E "D3DCompiler|libEGL|libGLESv2" +``` + +**See:** `references/electron-bundled-chromium-dll-fix.md` for full diagnosis and fix details.