fix: document electron module mapping and add native rebuild helper

2026-06-05 21:22:07 +00:00 · 2026-02-10 14:35:10 +01:00
parent ccbb744a41
commit a3ecbbe7b0
9 changed files with 6330 additions and 0 deletions
@@ -0,0 +1,109 @@
+# scoreko-electron-dev
+
+Wrapper de Electron para empaquetar una instalación de NodeCG que incluya el bundle `scoreko-dev`, inspirado en `opeik/runback-electron` pero actualizado a Electron + TypeScript moderno.
+
+Este wrapper está pensado para funcionar **standalone**: por defecto NodeCG corre con el **Node interno de Electron** (no requiere Node instalado en la máquina final).
+
+## Qué hace
+
+- Arranca `lib/nodecg/index.js` como proceso hijo desde Electron.
+- Muestra una ventana de carga mientras NodeCG inicia.
+- Carga el dashboard del bundle en `http://localhost:<puerto>/bundles/<bundle>/<ruta-dashboard>`.
+- Empaqueta NodeCG + assets dentro de la app final con `electron-builder`.
+
+## Estructura esperada
+
+```text
+scoreko-electron-dev/
+├─ lib/
+│  └─ nodecg/
+│     ├─ index.js
+│     ├─ node_modules/
+│     └─ bundles/
+│        └─ scoreko-dev/  # clonado/copiado desde tu repo scoreko-dev
+├─ src/main/main.ts
+├─ static/loading.html
+└─ package.json
+```
+
+## Preparación con tu repo `scoreko-dev`
+
+1. Copia o clona tu instalación de NodeCG en `lib/nodecg`.
+2. Copia tu bundle `scoreko-dev` a `lib/nodecg/bundles/scoreko-dev`.
+3. **Instala dependencias de NodeCG dentro de `lib/nodecg`**.
+4. Instala dependencias del wrapper:
+
+```bash
+npm install
+cd lib/nodecg
+npm install
+cd ../..
+```
+
+> Si no haces `npm install` dentro de `lib/nodecg`, verás errores como `Cannot find module ... node_modules/nodecg/dist/server/bootstrap.js`.
+
+## ¿Existe Electron con `NODE_MODULE_VERSION 127`?
+
+No en releases estables de Electron. Revisando la tabla oficial de releases de Electron, no aparece `modules=127`.
+
+- Electron 32.x usa `NODE_MODULE_VERSION 128`
+- Electron 34.x usa `NODE_MODULE_VERSION 132`
+- Electron 35.x usa `NODE_MODULE_VERSION 133`
+
+Por eso, para standalone hay que recompilar addons nativos contra la versión de Electron elegida.
+
+## Error típico: NODE_MODULE_VERSION
+
+Si ves un error como `better-sqlite3 ... NODE_MODULE_VERSION`, tienes módulos nativos compilados para una versión distinta de Node.
+
+En ese caso recompila contra Electron:
+
+```bash
+npm run rebuild:native
+```
+
+Este script ejecuta `electron-rebuild` en `lib/nodecg` y en el workspace SQLite legacy (si existe).
+
+Si sigues en modo standalone (default), asegúrate de no mezclar binarios compilados con otro runtime distinto al de Electron.
+
+## Runtime de NodeCG
+
+Por defecto (standalone):
+- `NODECG_USE_SYSTEM_NODE=false`
+
+Opcionalmente, puedes forzar Node del sistema:
+- `NODECG_USE_SYSTEM_NODE=true`
+- `NODECG_NODE_BINARY=node`
+
+Ejemplo en PowerShell para usar Node del sistema (si lo necesitas):
+
+```powershell
+$env:NODECG_USE_SYSTEM_NODE="true"
+$env:NODECG_NODE_BINARY="C:\Program Files\nodejs\node.exe"
+node -v
+npm run dev
+```
+
+## Variables de entorno opcionales
+
+Estas variables se leen en `src/main/main.ts`.
+
+- `NODECG_PORT` (default: `9090`)
+- `NODECG_BUNDLE_NAME` (default: `scoreko-dev`)
+- `SCOREKO_DASHBOARD_ROUTE` (default: `dashboard/index.html`)
+- `ELECTRON_LOAD_DELAY_MS` (default: `2500`)
+- `NODECG_STARTUP_TIMEOUT_MS` (default: `30000`)
+- `NODECG_USE_SYSTEM_NODE` (default: `false`)
+- `NODECG_NODE_BINARY` (default: `node`)
+
+## Scripts
+
+- `npm run dev`: modo desarrollo (watch + relanzado de Electron).
+- `npm run start`: build y ejecución local.
+- `npm run build`: compila TypeScript y copia assets.
+- `npm run pack`: genera app sin instalador.
+- `npm run dist`: genera instalador/plataformas configuradas.
+
+## Nota de seguridad
+
+La ventana principal usa `contextIsolation: true`, `sandbox: true` y `nodeIntegration: false`. Los enlaces externos se abren en el navegador del sistema.