Deployment, Packaging y Distributing de una aplicación en Electron.js a producción

Llevar una aplicación en Electron.js a producción no es ejecutar un comando y listo. Si ya has trabajado con Electron, probablemente tu app funcione perfectamente en desarrollo… hasta que intentas generar un ejecutable y empiezan los problemas.

En esta guía voy a explicar cómo hacer deployment, packaging y distribución de una app Electron de forma realista, apoyándome tanto en buenas prácticas como en errores que yo mismo cometí probando distintas herramientas. El objetivo no es solo que funcione, sino que entiendas qué estás haciendo y por qué.

Vamos a aprender no a actualizar nuestro proyecto en Electron, si no a generar una aplicación a producción lista para usar mediante un ejecutable; para ello, usaremos el siguiente paquete:

Qué significa realmente llevar una app Electron a producción

Por qué no existe un “comando mágico” para el deployment en Electron

Uno de los primeros golpes de realidad que me llevé fue entender que Electron no tiene un flujo único de despliegue. No existe algo como npm run deploy que mágicamente genere un .exe, un .dmg y un .deb listos para distribuir.

El deployment en Electron es un proceso, no un comando:

1. Compilar tu código (renderer + main)
2. Empaquetar la app
3. Crear instaladores
4. Firmar (si aplica)
5. Distribuir y actualizar

Cuando asumí esto, dejé de pelearme con las herramientas y empecé a usarlas mejor.

Diferencias clave entre desarrollo y entorno de producción en Electron

En desarrollo:

• Paths relativos “funcionan”
• Assets se cargan desde el sistema de archivos
• Node y Electron están siempre disponibles

En producción:

• El código va empaquetado
• Las rutas cambian
• Algunos archivos dejan de existir donde creías
• Windows es mucho menos permisivo

Varios bugs no tenían nada que ver con Electron en sí, sino con asumir que el entorno era igual al de desarrollo. Y no lo es.

Herramientas para empaquetar y distribuir Electron

Electron Forge: qué promete y cuándo tiene sentido usarlo

Electron Forge es la herramienta “oficial”. Promete:

• Scaffolding rápido
• Build pipeline completo
• Publicación integrada

Y todo eso es cierto… en el caso ideal. Cuando lo probé, funcionó bien para empezar, pero en cuanto quise controlar el output (especialmente en Windows), la experiencia se volvió frustrante: builds lentísimos, procesos que parecían colgados y documentación que omitía detalles clave.

Forge tiene sentido si:

Estás empezando

No necesitas mucho control

Aceptas la abstracción

Electron Builder: por qué suele ser la opción más predecible

Después de pelearme con Forge, terminé usando electron-builder, y la diferencia fue clara: menos magia, más control.

Electron-builder:

• Es explícito
• Vive en package.json
• Genera instaladores reales
• Se integra bien con CI/CD

No es perfecto, pero es predecible, y en producción eso vale oro.

Electron Forge vs Electron Builder: comparación

Si tuviera que empezar hoy un proyecto serio en Electron, iría directamente con electron-builder.

Preparar el proyecto Electron para el packaging

Estructura típica de un proyecto listo para producción

Un proyecto preparado para deployment suele separar claramente:

• main process
• renderer
• assets
• output de build

Esto no es capricho. El empaquetado funciona mejor cuando cada parte tiene su responsabilidad clara.

Main process, renderer y preload: lo que afecta al deployment

El preload script es especialmente importante. Al empaquetar:

• Se restringe el acceso a APIs
• Cambia el contexto de ejecución
• Aparecen errores silenciosos

En uno de mis builds, la app arrancaba… pero no hacía nada. El problema estaba en el preload, no en el renderer. En producción, estos errores son más difíciles de detectar si no los anticipas.

Problemas habituales con rutas y assets en producción

Este es uno de los errores más comunes: usar rutas que solo existen en dev.

Cuando empaquetas:

• __dirname ya no apunta donde crees
• Los assets pueden ir dentro del asar
• Las rutas absolutas dejan de funcionar

Aquí aprendí a testear siempre builds intermedios, no solo el instalador final.

Packaging de una aplicación Electron con electron-builder

Instalación correcta y dependencias (errores comunes incluidos)

Electron-builder debe ir en devDependencies. Si lo colocas en dependencies, el build falla. Me pasó, y el error no es especialmente amable.

https://www.electron.build/

Instalación correcta:

$ npm install electron-builder -D

Este detalle, aunque pequeño, bloquea completamente el deployment si no lo conoces.

Es importante notar que, este paquete, debes de instalarlo en cada proyecto de Electron.js cuando te interese generar los ejecutables de las aplicaciones, ya que, no es una dependencia que se instala a nivel global si no a nivel local.

Una vez instalado, configuramos los siguientes comandos para MacOS:

package.json

"scripts": {
  "serve": "vue-cli-service serve",
  "build": "vue-cli-service build",
  "lint": "vue-cli-service lint",
  "start": "DEBUG=true electron .",
  "dev:macos": "electron-builder --macos --dir",
  "pro:macos": "electron-builder --macos"
},

Para Linux:

package.json

"scripts": {
  ***
  "dev:linux": "electron-builder --linux --dir",
  "pro:linux": "electron-builder --linux"
},

Y para Windows:

package.json

"scripts": {
  ***
  "dev:windows": "electron-builder --win --dir",
  "pro:windows": "electron-builder --win"
},

Scripts por sistema operativo (Windows, macOS y Linux)

Una estrategia que me funcionó muy bien fue separar scripts:

• --dir para pruebas
• build completo para producción

Esto permite validar el paquete antes de generar el instalador, ahorrando muchísimo tiempo.

Generar el build

Luego es posible ejecutar cualquiera de los comandos según tu sistema operativo; por ejemplo:

$ npm run dev:macos

Para solamente generar la carpeta del paquete sin realmente empaquetarlo; esto es útil para fines de prueba

O

$ npm run pro:macos

Para empaquetar en un formato distribuible (por ejemplo, dmg, windows installer, deb package).

Al ejecutar el comando anterior, tendremos generado el proyecto como ejecutable:

<proyect>/dist

Al ejecutar el ejecutable, que en el caso de MacOS sería el DMG, en el caso de Windows, sería el EXE y en el caso de Linux, depende del sabor que estés usando, veremos la aplicación.

Otro detalle muy importante es que, dependiendo del proyecto que estés llevando a cabo, tengas que realizar modificaciones adicionales ya que, el espacio de trabajo es distinto; sobre todo con la integración con archivos externos cuyo directorio especificado al momento de desarrollar la aplicación no corresponde con la usada en producción, a lo largo del libro, veremos algunos ejemplos.

Generar ejecutables e instaladores: exe, dmg, deb y rpm

Con electron-builder puedes generar:

• .exe (NSIS)
• .dmg
• .deb
• .rpm

Todo desde el mismo proyecto, siempre que tengas el entorno adecuado. Aquí es donde electron-builder realmente brilla frente a Forge.

Errores frecuentes al empaquetar aplicaciones Electron

electron-builder en dependencies vs devDependencies

Este error es tan común que merece ser mencionado dos veces. Si ves un mensaje del tipo:

Package "electron-builder" is only allowed in devDependencies

Ya sabes por qué ocurre.

Problemas con NSIS, permisos y builds en Windows

Windows es, con diferencia, el sistema más problemático:

• Permisos
• Antivirus
• Instaladores bloqueados
• Builds lentos

Simplificar la configuración NSIS al inicio ahorra muchos dolores de cabeza.

Apps que funcionan en dev pero fallan en producción

Este es el clásico. Y casi siempre la causa es una de estas:

• Rutas
• Variables de entorno
• Dependencias no incluidas
• APIs no disponibles

Cuando algo falla en producción, asume primero que el entorno cambió, no que Electron “está roto”.

Distribución de la aplicación Electron

Opciones para distribuir tu app (web, GitHub, servidores propios)

Puedes distribuir tu app:

• Desde tu web
• Usando GitHub Releases
• Desde un servidor propio

No necesitas una store para empezar. De hecho, muchas apps Electron se distribuyen directamente como instaladores descargables.

Publicación automática y CI/CD para Electron

Automatizar el build cambia todo. Con CI:

• Evitas builds locales inconsistentes
• Generas releases reproducibles
• Centralizas errores

Aquí electron-builder se integra muy bien con GitHub Actions y otros pipelines.

Actualizaciones automáticas en aplicaciones Electron

Electron soporta auto-updates, pero:

• No es magia
• Requiere infraestructura
• Hay que planificarlo desde el inicio

Mi recomendación: no empieces por aquí. Primero consigue un build estable.

Consejos finales antes de generar tu ejecutable

Checklist rápida antes de hacer el build de producción

• ✔️ Rutas revisadas
• ✔️ Assets accesibles
• ✔️ electron-builder en devDependencies
• ✔️ Build con --dir probado
• ✔️ Logs habilitados

Qué haría distinto si empezara hoy un proyecto Electron

Si empezara hoy:

• Usaría electron-builder desde el día uno
• Probaría builds intermedios antes del instalador
• Asumiría que Windows va a dar problemas
• Diseñaría pensando en producción, no solo en dev

Conclusión

El deployment, packaging y distributing de una app en Electron.js no es trivial, pero tampoco es inabordable. La clave está en entender el proceso, elegir bien las herramientas y asumir que cometer errores es parte del camino.

Si algo he aprendido es que Electron funciona bien en producción, siempre que tú también hagas tu parte.