Electron Updater

OTA (Over-The-Air) updates for Electron applications. 100% feature parity with @capgo/capacitor-updater.

Open-source Alternative to Electron's built-in updater with live update capabilities.

Why Electron Updater?

Electron's built-in auto-updater requires shipping a full new binary for every update. This plugin solves that by:

• Instant updates - Push JavaScript/HTML/CSS updates directly to users without rebuilding the entire app
• Delta updates - Only download changed files, making updates ultra-fast
• Rollback protection - Automatically revert broken updates to keep your app stable
• Open source - Self-host or use Capgo Cloud, with full control over your update infrastructure
• Feature parity - Same API and capabilities as capacitor-updater

Perfect for fixing bugs immediately, A/B testing features, and maintaining control over your release schedule.

Features

• 🚀 Live Updates - Push updates instantly without app store review
• 🔄 Auto-Update - Automatic update checking and installation
• 🛡️ Rollback Protection - Automatic rollback if update fails
• 📦 Bundle Management - Full control over downloaded bundles
• 🔐 End-to-End Encryption - Secure update delivery
• 📊 Channel System - Deploy to different user groups
• ⏱️ Delay Conditions - Control when updates are applied
• 🐛 Debug Menu - Built-in debug tools for development

Installation

npm install @capgo/electron-updater

Quick Start

Main Process

// main.ts
import { app, BrowserWindow } from 'electron';
import * as path from 'path';
import {
  ElectronUpdater,
  setupIPCHandlers,
  setupEventForwarding,
} from '@capgo/electron-updater';

const updater = new ElectronUpdater({
  appId: 'com.example.app',
  autoUpdate: true,
});

app.whenReady().then(async () => {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });

  // Initialize updater with window and builtin path
  const builtinPath = path.join(__dirname, 'www/index.html');
  await updater.initialize(mainWindow, builtinPath);

  // Setup IPC communication
  setupIPCHandlers(updater);
  setupEventForwarding(updater, mainWindow);

  // Load the current bundle (either builtin or downloaded)
  await mainWindow.loadFile(updater.getCurrentBundlePath());
});

Preload Script

// preload.ts
import { exposeUpdaterAPI } from '@capgo/electron-updater/preload';

exposeUpdaterAPI();

Renderer Process

// renderer.ts
import { requireUpdater } from '@capgo/electron-updater/renderer';

const updater = requireUpdater();

// IMPORTANT: Call this on every app launch!
await updater.notifyAppReady();

// Check for updates manually
const latest = await updater.getLatest();
if (latest.url && !latest.error) {
  // Download the update
  const bundle = await updater.download({
    url: latest.url,
    version: latest.version,
    checksum: latest.checksum,
  });

  // Queue for next restart
  await updater.next({ id: bundle.id });
}

// Listen for events
updater.addListener('download', (event) => {
  console.log(`Download progress: ${event.percent}%`);
});

updater.addListener('updateFailed', (event) => {
  console.error('Update failed:', event.bundle.version);
});

API Reference

Core Methods

| Method | Description | |--------|-------------| | notifyAppReady() | Must be called on every launch - Confirms bundle loaded successfully | | download(options) | Download a bundle from URL | | next(options) | Queue bundle for next restart | | set(options) | Immediately switch to bundle and reload | | reload() | Reload the app with current bundle | | delete(options) | Delete a bundle from storage | | reset(options) | Reset to builtin or last successful bundle |

Bundle Information

| Method | Description | |--------|-------------| | current() | Get current bundle and native version | | list(options) | List all downloaded bundles | | getNextBundle() | Get bundle queued for next restart | | getFailedUpdate() | Get info about last failed update | | getBuiltinVersion() | Get version shipped with app |

Update Checking

| Method | Description | |--------|-------------| | getLatest(options) | Check server for latest version |

Channel Management

| Method | Description | |--------|-------------| | setChannel(options) | Assign device to a channel | | unsetChannel(options) | Remove channel assignment | | getChannel() | Get current channel | | listChannels() | List available channels |

Delay Conditions

| Method | Description | |--------|-------------| | setMultiDelay(options) | Set conditions before update applies | | cancelDelay() | Clear all delay conditions |

Delay condition types:

• background - Wait for app to be backgrounded (with optional duration)
• kill - Wait for app to be killed and restarted
• date - Wait until specific date/time
• nativeVersion - Wait for native app update

Device Identification

| Method | Description | |--------|-------------| | getDeviceId() | Get unique device ID | | setCustomId(options) | Set custom identifier |

Configuration

| Method | Description | |--------|-------------| | setUpdateUrl(options) | Change update server URL | | setStatsUrl(options) | Change statistics URL | | setChannelUrl(options) | Change channel URL | | setAppId(options) | Change App ID | | getAppId() | Get current App ID |

Debug

| Method | Description | |--------|-------------| | setDebugMenu(options) | Enable/disable debug menu | | isDebugMenuEnabled() | Check debug menu state |

Events

| Event | Description | |-------|-------------| | download | Download progress updates | | updateAvailable | New update available | | noNeedUpdate | Already up-to-date | | downloadComplete | Download finished | | downloadFailed | Download failed | | breakingAvailable | Incompatible update available | | updateFailed | Update installation failed | | appReloaded | App was reloaded | | appReady | notifyAppReady() was called |

Configuration Options

const updater = new ElectronUpdater({
  // Core
  appId: 'com.example.app',
  version: '1.0.0', // Override builtin version
  autoUpdate: true, // Enable auto-updates (default: true)
  appReadyTimeout: 10000, // MS before rollback (default: 10000)

  // Server URLs
  updateUrl: 'https://plugin.capgo.app/updates',
  channelUrl: 'https://plugin.capgo.app/channel_self',
  statsUrl: 'https://plugin.capgo.app/stats',

  // Security
  publicKey: '...', // For E2E encryption

  // Channels
  defaultChannel: 'production',

  // Behavior
  autoDeleteFailed: true, // Delete failed bundles
  autoDeletePrevious: true, // Delete old bundles
  resetWhenUpdate: true, // Reset on native update

  // Direct Update
  directUpdate: false, // 'atInstall' | 'onLaunch' | 'always' | false

  // Dynamic Config
  allowModifyUrl: false, // Allow runtime URL changes
  allowModifyAppId: false, // Allow runtime App ID changes
  persistCustomId: false, // Persist custom ID
  persistModifyUrl: false, // Persist URL changes

  // Debug
  debugMenu: false, // Enable debug menu (Ctrl+Shift+D)
  disableJSLogging: false, // Disable console logs

  // Periodic Updates
  periodCheckDelay: 0, // Seconds between checks (0 = disabled, min 600)
});

Rollback Protection

The updater includes automatic rollback protection:

1. When a new bundle loads, a timer starts (default: 10 seconds)
2. Your app must call notifyAppReady() before the timer expires
3. If the timer expires, the update is considered failed
4. The app automatically rolls back to the last successful bundle

This prevents broken updates from bricking your app.

Debug Menu

Enable the debug menu during development:

const updater = new ElectronUpdater({
  debugMenu: true,
});

Access with Ctrl+Shift+D (or Cmd+Shift+D on Mac) to:

• View current bundle information
• Switch between available bundles
• Reset to builtin version
• View device and channel info

Differences from Capacitor Updater

| Feature | Capacitor Updater | Electron Updater | |---------|-------------------|------------------| | Shake Menu | Physical shake | Keyboard shortcut | | Background Detection | Native events | Window blur/focus | | Storage | Native filesystem | userData directory | | Device ID Storage | Keychain/Keystore | safeStorage |

Documentation

Full documentation is available at capgo.app/docs.

Community

Join the discord to get help.

License

Mozilla Public License Version 2.0. See LICENSE for details.