Master Electron Packaging: A Deep Dive into electron-builder

When developing Electron desktop applications, simply running electron . is not enough; you need to package the app into a polished executable with installers and auto‑update support. This is where electron-builder comes into play.

electron-builder is a powerful and popular build tool that automates the packaging and distribution of Electron apps. It bundles your project, binds it to the correct Electron version, and generates platform‑specific installer formats such as .exe for Windows, .dmg for macOS, and .AppImage or .deb for Linux.

In this article we explore the inner workings of electron-builder , its main components, and how to use it effectively.

2. How to Set Up

A basic Electron project can add electron-builder with the following command: npm install --save-dev electron-builder In your package.json you typically configure it like this:

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "main.js",
  "build": {
    "appId": "com.example.myapp",
    "productName": "MyElectronApp",
    "directories": { "buildResources": "assets" },
    "files": ["dist/**/*", "main.js"],
    "mac": { "category": "public.app-category.utilities" },
    "win": { "target": "nsis" },
    "linux": { "target": ["AppImage", "deb"] }
  },
  "scripts": { "build": "electron-builder" }
}

Key points: build field controls how the app is packaged. files tells electron-builder which files to include in the final app. directories defines where icons, extra resources, or custom assets reside.

Platform‑specific settings ( mac, win, linux) let you fine‑tune each target.

Run the build with: npm run build This triggers electron-builder to package, sign (if configured), and output installable files to the dist/ folder.

3. Deep Dive

a) Packaging vs. Compilation

electron-builder does not bundle your code like Webpack or Vite; it expects a pre‑built JavaScript folder (e.g., dist/). Many projects use scripts such as:

{
  "scripts": {
    "build:main": "tsc -p tsconfig.main.json",
    "build:renderer": "webpack --config webpack.renderer.config.js",
    "build": "npm run build:main && npm run build:renderer && electron-builder"
  }
}

First you compile the main and renderer processes, then electron-builder packages the result.

b) Application Injection

When building for Windows, macOS, or Linux, electron-builder downloads the correct Electron binary for the target OS/architecture and copies your files into the resources/app folder. The resulting .exe or .app is essentially the Electron binary launching your custom code.

🐍 Appendix: Including Python in Electron

Sometimes an Electron app needs Python scripts for data processing, automation, or AI tasks. Use PyInstaller or py2exe to compile the script into an executable, place it in a folder (e.g., python-bin/), and add that folder to the files list in package.json. At runtime, spawn the binary via Node’s child_process.spawn.

✅ Example: Adding a Python Executable

Assume you have a Python script script.py and compile it with: pyinstaller --onefile script.py This creates dist/script.exe. Include it in the build configuration:

{
  "name": "electron-python-app",
  "version": "1.0.0",
  "main": "dist/main.js",
  "scripts": {
    "build:main": "tsc",
    "build:renderer": "webpack --config webpack.renderer.config.js",
    "build": "npm run build:main && npm run build:renderer && electron-builder",
    "start": "electron ."
  },
  "build": {
    "appId": "com.example.electronpython",
    "productName": "ElectronPythonApp",
    "files": ["dist/**/*", "public/**/*", "python-bin/**"],
    "win": { "target": "nsis" }
  },
  "devDependencies": {
    "electron": "^30.0.0",
    "electron-builder": "^24.15.3",
    "typescript": "^5.3.3",
    "webpack": "^5.91.0",
    "webpack-cli": "^5.1.4"
  }
}

📁 Project Folder Example

electron-python-app/
├── package.json
├── dist/
│   ├── main.js
│   ├── renderer.js
├── public/
│   └── index.html
├── python-bin/
│   └── script.exe   ✅ compiled Python binary

✏️ Running the Python Binary

In main.ts (or main.js) use Node’s child_process to spawn the binary:

import { spawn } from 'child_process';
import { app, BrowserWindow } from 'electron';
import * as path from 'path';

function runPython() {
  const pythonExe = path.join(process.resourcesPath, 'python-bin', 'script.exe');
  const child = spawn(pythonExe, ['--arg1', 'foo']);
  child.stdout.on('data', data => console.log(`Python output: ${data}`));
  child.stderr.on('data', data => console.error(`Python error: ${data}`));
  child.on('close', code => console.log(`Python script exited with code ${code}`));
}

app.whenReady().then(() => {
  const win = new BrowserWindow({ width: 800, height: 600 });
  win.loadFile('public/index.html');
  runPython();
});

4. Code Signing & Verification

Modern OSes expect signed applications. If you provide a Windows .pfx certificate (with password) or a valid macOS Apple Developer ID, electron-builder can automatically sign your builds using native tools ( signtool.exe, codesign, altool).

5. Auto‑Update

electron-builder works with electron-updater to enable automatic updates. When you run the build, it can publish artifacts to GitHub Releases, S3, or a custom server. The app periodically checks a JSON feed, downloads new versions, and restarts to apply the update.

6. Common Tips & Gotchas

Cross‑platform builds : You can generate Windows installers on macOS/Linux, but Windows code signing may require Windows tools or CI runners.

Version mismatch : Ensure the Electron version in package.json matches the version expected by electron-builder .

Packaging debugging : If files are missing from the installer, check the files field.

macOS notarization pain : Set APPLE_ID and APPLE_APP_SPECIFIC_PASSWORD environment variables for proper notarization.

7. Summary

electron-builder makes releasing Electron applications easy. It does not replace your bundler but automates the following workflow:

Package your app with Electron.

Generate production‑ready installers.

Sign and verify for OS trust.

Upload releases and enable auto‑updates.

Its flexibility and mature ecosystem make it the go‑to choice for Electron packaging.