ElVendedorDocs

Despliegue de la app de escritorio

Empaqueta ElVendedor Desktop con Electron Forge: instaladores Windows y Linux, URL del backend incrustada, staging y verificación de artefactos.

Para implementadores4 min de lecturaActualizado el 16 de noviembre de 2026

El escritorio se empaqueta con Electron Forge y se reparte como instalador o ZIP portable. La URL del servidor de sincronización se incrusta en el paquete y no se puede editar después. Al terminar sabrás generar los artefactos de cada plataforma, apuntarlos a tu backend, validarlos con su checksum y distinguir producción de staging.

Antes de empezar

  • Node.js 22 o superior y npm ci en la raíz del repositorio.
  • En Linux: dpkg-deb y fakeroot para el .deb; rpmbuild solo si quieres el .rpm.
  • En Linux para el instalador de Windows: wine + mono, si pretendes generarlo fuera de Windows.
sudo apt-get update && sudo apt-get install -y dpkg-dev fakeroot rpm

Flujo de empaquetado

Comando Qué hace
npm run package electron-forge package; arma la app sin instalador
npm run make electron-forge make; genera los paquetes de la plataforma actual
npm run dist node scripts/dist.js; orquesta todo y publica en dist/
npm run dist:linux .deb (+ .rpm si hay rpmbuild) y .zip
npm run dist:win Setup.exe de Squirrel y .zip (en Linux solo el ZIP)
npm run dist:all Linux y Windows desde el host actual

scripts/dist.js corre antes la suite de pruebas. Para saltarla porque ya la corriste:

npm run dist:linux -- --skip-tests
npm run dist:win -- --arch=arm64
npm run dist:linux -- --plan                       # solo muestra el plan
npm run dist:linux -- --targets=@electron-forge/maker-zip

Los makers dependen del host: en Linux se construyen deb, rpm y zip; en Windows, squirrel y zip. Si falta rpmbuild o no estás en Windows, el script omite ese maker y avisa. La variable EVD_SKIP_MAKERS permite forzar la omisión desde herramientas externas.

URL del backend al empaquetar

El orden de prioridad al construir es:

  1. VITE_SYNC_API_URL en la máquina o en CI.
  2. .env.staging si EVD_ENV=staging.
  3. .env.production (por defecto https://elvendedor.laravel.cloud/api/v1).
  4. http://127.0.0.1:8000/api/v1 solo para desarrollo y tests.
# Backend on-premise u otro entorno
VITE_SYNC_API_URL=https://mi-servidor.example/api/v1 npm run dist:linux -- --skip-tests
# .env.production
VITE_SYNC_API_URL=https://elvendedor.laravel.cloud/api/v1

# .env.staging (se carga con EVD_ENV=staging)
VITE_SYNC_API_URL=https://elvendedor-staging-staging-ydffdy.laravel.cloud/api/v1

La URL queda dentro del paquete: login y pantalla de sincronización no la muestran ni la dejan editar, y en los diagnósticos aparece como [servidor]. Si el cliente cambia de servidor, hay que volver a empaquetar.

Salidas y verificación

Todo queda en dist/<version>/<plataforma>/, con SHA256SUMS.txt por plataforma, otro global en dist/<version>/ y un BUILD-INFO.txt con versión, commit, fecha, host y artefactos.

# Comprobar el .deb
dpkg-deb --info dist/2.1.6/linux/el-vendedor-desktop_2.1.6_amd64.deb
dpkg-deb --contents dist/2.1.6/linux/el-vendedor-desktop_2.1.6_amd64.deb | head

# Instalarlo en Debian/Ubuntu
sudo apt install ./dist/2.1.6/linux/el-vendedor-desktop_2.1.6_amd64.deb

# Verificar checksums publicados
sha256sum -c SHA256SUMS.txt

Antes de entregar: npm test en verde, SHA256SUMS.txt sin errores, la app abre, muestra su versión y permite iniciar sesión y sincronizar; en Windows el instalador crea accesos directos y desinstala desde Configuración; en Linux el lanzador aparece en el menú (categoría Oficina).

Staging frente a producción

EVD_ENV=staging cambia el nombre técnico a el-vendedor-desktop-staging, el appBundleId a com.elvendedor.desktop.staging y usa .env.staging. Así ambas versiones se instalan a la vez y no comparten datos locales ni backend.

npm run dist:linux:staging
npm run dist:win:staging

Puerto de Vite y almacenamiento local

En desarrollo el servidor de Vite usa el puerto 5174 (o EVD_DEV_PORT). Ese puerto es la identidad del almacenamiento: cambiarlo abre otra base local, con datos distintos. Solo afecta al desarrollo; el binario empaquetado no depende del puerto y guarda su perfil en la ruta histórica el-vendedor-desktop-vite para que actualizar no haga desaparecer la base PouchDB.

Dependencias del host

Herramienta Para qué Plataforma
dpkg-deb + fakeroot Construir el .deb Linux
rpmbuild (paquete rpm) Construir el .rpm Linux
wine + mono Instalador Squirrel Linux hacia Windows
Node 22 + npm Todo el flujo Ambas

Integración continua

.github/workflows/distribucion.yml se dispara con un tag v* o a mano (workflow_dispatch). Compila en ubuntu-latest y windows-latest, usa SYNC_API_URL como variable de repositorio si está definida, comprueba que el tag coincida con package.json, corre npm test, construye con npm run dist:<platform> -- --skip-tests, valida los artefactos de Windows (*Setup.exe de más de 1 MB, ZIP, SHA256SUMS.txt, ProductName y CompanyName) y crea la release de GitHub solo cuando el disparo es un tag.

Pendiente de validación

Los artefactos salen sin firmar: Windows mostrará SmartScreen hasta que se compre un certificado y no hay actualizaciones automáticas (no existe servidor de updates). Confirma con el Lead si se firma en el futuro y cómo se comunica el aviso al cliente.

Problemas frecuentes

Síntoma Causa habitual Solución
Falta el .rpm No hay rpmbuild en el host Instala rpm o déjalo a CI
No aparece Setup.exe Squirrel necesita Windows o wine + mono Usa Windows, CI o el ZIP portable
La app apunta a otro servidor La URL se fijó al empaquetar Reconstruye con VITE_SYNC_API_URL
Actualizar "perdió" los datos Perfil local movido a propósito No cambies la ruta de userData; verifica src/main.js

Siguiente paso

↑↓ para navegar · Enter para abrir · Esc para cerrar