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

```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.