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

``bash
npm install @capgo/electron-updater
`

Quick Start

$3

`typescript
// 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());
});
`

$3

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

exposeUpdaterAPI();
`

$3

`typescript
// 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

$3

| 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 |

$3

| 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 |

$3

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

$3

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

$3

| 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

$3

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

$3

| 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 |

$3

| 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

`typescript
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:

`typescript
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.