atomk-hermes-skills/skills/devops/electron-build/SKILL.md

name, description, version, author, license, metadata

name	description	version	author	license	metadata
electron-build	Electron desktop app builds: cross-compile for Windows on Linux and fix bundled Chromium DLL issues.	1.0.0	Hermes Agent	MIT	hermes tags related_skills electron windows cross-compile nsis exe msi wine chromium dll-fix build 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

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install -y wine32:i386 wine64

Disable Code Signing (no certificate)

"win": {
  "target": ["nsis", "portable"],
  "icon": "assets/icon.ico",
  "signAndEditExecutable": false,
  "sign": null
}

Build

npm run build:win
# Output: dist/*.exe, dist/*.msi

Full Build-to-Deploy Workflow (AtomK Desktop)

# 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/<build>/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

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.