fix: handle node module mismatch and startup readiness

2026-06-06 05:32:06 +00:00 · 2026-02-10 14:04:50 +01:00
parent ccbb744a41
commit 0dc7d213b9
8 changed files with 6142 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 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.
+
+## 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`.
+
+
+## Error típico: NODE_MODULE_VERSION (Node 22 vs Electron Node 20)
+
+Si ves un error como `better-sqlite3 ... NODE_MODULE_VERSION`, tienes módulos nativos compilados para una versión distinta de Node.
+
+1. Entra a `lib/nodecg`.
+2. Reinstala/recompila dependencias nativas:
+
+```bash
+cd lib/nodecg
+npm install
+npm rebuild better-sqlite3 --update-binary
+```
+
+3. Si persiste, elimina `node_modules` del workspace que falla y vuelve a instalar.
+
+## 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`)
+
+Ejemplo (PowerShell):
+
+```powershell
+$env:NODECG_PORT="9191"
+$env:NODECG_BUNDLE_NAME="scoreko-dev"
+npm run dev
+```
+
+## 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.