Distributing JavaScript Applications: Electron Desktop Apps vs Node.js Binaries

When shipping JavaScript applications to end users, the choice of packaging tool depends heavily on whether you are building a graphical desktop app or a command-line utility. electron-builder, electron-packager, and pkg solve different parts of this puzzle. Let's break down how they handle the complexities of distribution, native modules, and updates.

🖥️ Target Environment: Desktop GUI vs Headless Node

electron-builder is designed specifically for Electron apps.

• It bundles your code with the Chromium runtime and Node.js.
• Produces installers (.exe, .dmg) ready for end users.

// electron-builder: package.json config
{
  "build": {
    "appId": "com.example.app",
    "win": {
      "target": "nsis"
    }
  }
}

electron-packager also targets Electron apps but is more bare-bones.

• It packages the source and runtime but does not create installers by default.
• You get a directory with the executable, not a setup file.

// electron-packager: CLI usage
electron-packager ./app MyApp --platform=win32 --arch=x64
// Outputs: MyApp-win32-x64/MyApp.exe

pkg targets standard Node.js projects, not Electron.

• It compiles your script into a binary that includes the Node runtime.
• No Chromium browser is included, so it cannot render HTML/CSS GUIs.

// pkg: package.json config
{
  "pkg": {
    "targets": [ "node18-win-x64" ],
    "outputPath": "dist"
  }
}

⚙️ Configuration: Convention vs Flexibility

electron-builder relies on a centralized config.

• You define settings in package.json or a separate YAML file.
• Handles code signing and notarization automatically if configured.

// electron-builder: electron-builder.yml
appId: com.example.app
mac:
  category: public.app-category.productivity
  notarize: true

electron-packager uses CLI flags or an API object.

• Configuration is passed directly during the build command.
• Less opinionated, meaning you manage more details manually.

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

await packager({
  dir: './app',
  name: 'MyApp',
  platform: 'darwin',
  arch: 'x64'
});

pkg uses a pkg section in package.json.

• You specify entry points and assets to include in the binary.
• Focuses on file system paths and Node version targets.

// pkg: package.json scripts
{
  "scripts": {
    "build": "pkg ."
  },
  "pkg": {
    "assets": "views/**/*"
  }
}

🧩 Native Modules: Rebuilding vs Baking In

electron-builder rebuilds native modules automatically.

• It detects node-gyp dependencies and compiles them for Electron's Node version.
• Crucial for apps using hardware access or system libraries.

// electron-builder: Handles native deps internally
// No extra command needed if configured in package.json
{
  "build": {
    "npmRebuild": true
  }
}

electron-packager does not rebuild modules by default.

• You must run electron-rebuild separately before packaging.
• Adds an extra step to your CI/CD pipeline.

// electron-packager: Manual rebuild step
npm run electron-rebuild
electron-packager ./app MyApp --platform=win32

pkg bakes native modules into the binary.

• It analyzes require statements and includes compiled .node files.
• Sometimes requires manual configuration for dynamic imports.

// pkg: Handling native modules
// pkg automatically includes known native modules
// For dynamic paths, you must specify in package.json
{
  "pkg": {
    "scripts": "dist/**/*.js"
  }
}

🔄 Auto-Updates: Built-In vs DIY

electron-builder has deep integration with update servers.

• Works seamlessly with electron-updater for S3, GitHub, or generic hosts.
• Handles download, verification, and installation silently.

// electron-builder: Auto-update config
{
  "publish": {
    "provider": "github",
    "owner": "me",
    "repo": "my-app"
  }
}

electron-packager provides no update mechanism.

• You must implement your own update logic using electron-updater.
• Gives you full control but requires significant engineering effort.

// electron-packager: Manual update implementation
// You must install and configure electron-updater separately
const { autoUpdater } = require('electron-updater');
autoUpdater.checkForUpdatesAndNotify();

pkg does not support auto-updates natively.

• Since it produces a static binary, updates require replacing the file.
• Typically handled by external package managers like npm or brew.

// pkg: No built-in updater
// Users typically update via:
npm install -g my-cli@latest

📦 Output Artifacts: Installers vs Binaries

electron-builder generates platform-specific installers.

• Creates .exe (NSIS/MSI), .dmg, .deb, .rpm, etc.
• Ready for distribution to non-technical users.

// electron-builder: Output example
// dist/
//   MyApp Setup 1.0.0.exe
//   MyApp-1.0.0.dmg
//   MyApp-1.0.0.AppImage

electron-packager outputs application directories.

• Produces a folder containing the executable and resources.
• Often zipped manually for distribution.

// electron-packager: Output example
// MyApp-win32-x64/
//   MyApp.exe
//   resources/
//   version

pkg produces a single standalone executable.

• One file contains the runtime and your code.
• Ideal for CLI tools where simplicity is key.

// pkg: Output example
// dist/
//   my-cli-win.exe
//   my-cli-macos
//   my-cli-linux

🌱 Similarities: Shared Ground Between Tools

While they target different runtimes, these tools share common goals in the JavaScript ecosystem.

1. 📦 Cross-Platform Compilation

• All three allow building for Windows, macOS, and Linux from a single machine.
• Use flags or config to specify target architectures (x64, arm64).

// electron-builder: Multi-platform build
"build": { "linux": { "target": "deb" }, "win": { "target": "portable" } }

// electron-packager: Multi-platform flag
--platform=all --arch=x64

// pkg: Multi-platform targets
"targets": [ "node18-linux-x64", "node18-win-x64", "node18-macos-x64" ]

2. 🔒 Code Signing Support

• All support signing executables to satisfy OS security requirements.
• electron-builder automates this; others require manual setup.

// electron-builder: Automated signing
"win": { "sign": "./sign-script.js" }

// electron-packager: Manual signing post-build
// Use osx-sign or signtool after packaging

// pkg: Relies on external tools
// Sign the resulting binary with codesign or signtool

3. 🛠️ CLI and API Usage

• Each tool can be run from the command line or imported as a module.
• Fits into custom npm scripts or CI/CD pipelines easily.

// electron-builder: CLI
npx electron-builder --win

// electron-packager: CLI
electron-packager . MyApp

// pkg: CLI
pkg index.js --targets node18

4. 📂 Asset Management

• All require explicit configuration to include non-code assets.
• Images, configs, and views must be declared to avoid missing files.

// electron-builder: Files config
"files": [ "**/*", "!**/.git" ]

// electron-packager: Ignore patterns
--ignore="^(src|test)$"

// pkg: Assets config
"pkg": { "assets": "public/**/*" }

5. 🚀 Production Readiness

• All are used in production environments by major companies.
• Support minification and obfuscation via external tools.

// Common pattern: Webpack + Packager
// Bundle code with Webpack first, then package

// electron-builder + Webpack
"main": "dist/main.js"

// pkg + Webpack
"pkg": { "scripts": "dist/**/*.js" }

📊 Summary: Key Similarities

🆚 Summary: Key Differences

💡 The Big Picture

electron-builder is the complete solution 🧰 for desktop apps. It handles the messy details of signing, installers, and updates so you can focus on features. Use this for 90% of Electron projects.

electron-packager is the raw material 🪵 for Electron. It gives you the packaged app without the installer logic. Use this if you are building a custom distribution system or need a simpler build step for internal tools.

pkg is the specialist 🔧 for Node.js binaries. It skips the browser entirely to make lightweight CLI tools. Use this when you don't need a GUI and want a single file that runs anywhere.

Final Thought: Don't force a tool to do a job it wasn't designed for. If you need a desktop interface, pick an Electron tool. If you need a command-line utility, pick pkg. Within Electron, choose electron-builder for ease and electron-packager for control.