Electron Packaging Tools: Architecture, Workflow, and Native Modules

Building a production-ready Electron application requires more than just writing JavaScript. You need to bundle the Chromium runtime, package your source code into executables, handle native dependencies, and often create installers. The ecosystem offers distinct tools for these tasks: @electron/packager, electron-builder, the legacy electron-packager, and electron-rebuild. Let's examine how they fit into a professional build pipeline.

📦 Core Purpose: Packaging vs. Building Installers

The most critical distinction is between packaging (creating the app bundle) and building (creating the installer).

@electron/packager focuses strictly on packaging. It takes your source and the Electron binary and outputs a folder structure (e.g., MyApp.app or MyApp.exe). It does not create installers by default.

# @electron/packager: CLI usage
npx @electron/packager ./src MyApp --platform=darwin --arch=x64
# Output: ./MyApp-darwin-x64/MyApp.app

electron-builder handles the entire lifecycle. It packages the app AND creates installers (DMG, NSIS, AppImage, etc.). It also manages code signing and notarization automatically.

# electron-builder: CLI usage
npx electron-builder --mac --win
# Output: ./dist/MyApp.dmg, ./dist/MyApp Setup.exe

electron-packager (legacy) functioned similarly to @electron/packager but is no longer maintained for new feature work. It produces app bundles but lacks the modern scoped package structure.

# electron-packager: Legacy CLI usage
npx electron-packager ./src MyApp --platform=darwin --arch=x64
# Output: ./MyApp-darwin-x64/MyApp.app

electron-rebuild does not package apps. It compiles native modules. You run this before packaging to ensure C++ addons match Electron's Node version.

# electron-rebuild: CLI usage
npx electron-rebuild -v 30.0.0 -f
# Rebuilds node_modules against Electron v30 headers

🔌 Native Module Handling

Electron bundles its own version of Node.js, which often differs from your system's Node version. Native modules (like sqlite3 or node-serialport) must be recompiled to work.

@electron/packager does not automatically rebuild native modules. You must run a rebuild step separately or use a hook.

// @electron/packager: Programmatic usage with hook
const packager = require('@electron/packager');

await packager({
  dir: './src',
  name: 'MyApp',
  afterCopy: [(buildPath, electronVersion, platform, arch, callback) => {
    // Manually trigger rebuild logic here
    callback();
  }]
});

electron-builder has native module rebuilding built-in. It detects node-gyp dependencies and rebuilds them automatically during the build process.

// electron-builder: package.json config
{
  "build": {
    "npmRebuild": true,
    "nativeRebuilder": {
      "parallel": true
    }
  }
}

electron-packager shares the same limitation as its successor. It requires manual intervention for native modules.

// electron-packager: Programmatic usage
const packager = require('electron-packager');

await packager({
  dir: './src',
  name: 'MyApp',
  // No built-in native rebuild, requires external script
});

electron-rebuild is the dedicated solution for this problem. It is often used alongside @electron/packager to fill the gap.

// electron-rebuild: Programmatic usage
const Rebuild = require('electron-rebuild').default;

const rebuilder = new Rebuild({
  buildPath: __dirname,
  electronVersion: '30.0.0',
  arch: 'x64'
});

await rebuilder.rebuild();

⚙️ Configuration Complexity

Configuration style varies from simple CLI flags to complex JSON schemas.

@electron/packager uses a straightforward API or CLI flags. It is minimalistic.

// @electron/packager: JS API
const options = {
  dir: '.',
  name: 'MyApp',
  platform: 'linux',
  arch: 'x64',
  electronVersion: '30.0.0'
};

electron-builder relies heavily on package.json or electron-builder.yml. It is opinionated and verbose but powerful.

# electron-builder: electron-builder.yml
appId: com.example.app
mac:
  category: public.app-category.productivity
  target: dmg
win:
  target: nsis

electron-packager uses a similar API to @electron/packager but is tied to the legacy namespace.

// electron-packager: JS API
const options = {
  dir: '.',
  name: 'MyApp',
  platform: 'linux',
  arch: 'x64'
};

electron-rebuild is configured via CLI flags or a constructor object, focusing solely on build paths and versions.

# electron-rebuild: CLI flags
npx electron-rebuild --path ./src --version 30.0.0 --force

🛡️ Code Signing and Notarization

For macOS and Windows distribution, signing is mandatory.

@electron/packager supports signing via plugins or the osxSign option (often delegated to @electron/osx-sign). It does not handle notarization out of the box.

// @electron/packager: Signing config
await packager({
  ...options,
  osxSign: {
    identity: 'Developer ID Application: My Name'
  }
});

electron-builder automates signing and notarization. It reads environment variables (like CSC_LINK) and handles the entire flow.

// electron-builder: package.json
{
  "build": {
    "mac": {
      "hardenedRuntime": true,
      "gatekeeperAssess": false
    }
  }
}

electron-packager supports signing similarly to @electron/packager but lacks ongoing support for new OS security requirements.

// electron-packager: Signing config
await packager({
  ...options,
  osxSign: true
});

electron-rebuild does not handle signing. It is strictly for compilation.

# electron-rebuild: No signing capabilities
# N/A

🔄 Update Mechanisms

Shipping the app is only step one; updating it is another.

@electron/packager provides no update mechanism. You must implement electron-updater or a custom solution manually.

// @electron/packager: Manual update implementation
// Requires separate library like electron-updater
const { autoUpdater } = require('electron-updater');
autoUpdater.checkForUpdatesAndNotify();

electron-builder integrates tightly with electron-updater. It publishes artifacts to GitHub, S3, or Spaces automatically.

// electron-builder: Publish config
{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "my-org",
      "repo": "my-app"
    }
  }
}

electron-packager like its successor, requires manual update implementation.

// electron-packager: Manual update implementation
// Requires separate library setup
const { autoUpdater } = require('electron-updater');

electron-rebuild is unrelated to app updates.

# electron-rebuild: N/A

📊 Summary: Tool Responsibilities

💡 The Big Picture

electron-builder is the heavy lifter 🏋️. If you need to ship a signed, installable product with auto-updates tomorrow, choose this. It abstracts the complexity of notarization and installer creation, which saves weeks of configuration time.

@electron/packager is the precision instrument 🔬. Use this if you are building a custom CI/CD pipeline where you want to separate packaging from signing and installer creation. It is also the correct choice if you are distributing portable apps (just the folder) rather than installers.

electron-packager is the legacy tool 🕰️. It exists for backwards compatibility. Do not start new projects with it. Migrate existing projects to @electron/packager to ensure compatibility with future Electron releases.

electron-rebuild is the specialist 🔧. You might not need it directly if you use electron-builder, but if you use @electron/packager and have native dependencies, this tool (or its logic integrated into your scripts) is mandatory to prevent runtime crashes.

Final Thought: For most teams, electron-builder offers the best balance of power and convenience. However, understanding @electron/packager is valuable for debugging build issues, as electron-builder often uses packaging logic similar to it under the hood. Always ensure native modules are rebuilt regardless of which packager you choose.