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.
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 cien la raíz del repositorio. - En Linux:
dpkg-debyfakerootpara el.deb;rpmbuildsolo 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 rpmFlujo 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-zipLos 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:
VITE_SYNC_API_URLen la máquina o en CI..env.stagingsiEVD_ENV=staging..env.production(por defectohttps://elvendedor.laravel.cloud/api/v1).http://127.0.0.1:8000/api/v1solo 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/v1La 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.txtAntes 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:stagingPuerto 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
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte