Integration Guide for Electron Auto-Update
Learn how to integrate automatic updates into your Electron application using our release management platform. This guide covers manual downloads, API endpoints, and complete auto-update configuration.
Getting Started
Our platform provides a simple and secure way to distribute updates for your Electron application. You can either download releases manually or configure automatic updates using our API.
Base URL: All API endpoints are available at your deployed instance URL. Replace YOUR_DOMAIN with your actual domain.
Supported Platforms
Windows
.exe
win32macOS
.dmg, .zip
darwinLinux
.flatpak
linuxManual Download
Browse available releases and download binaries directly for your platform.
Steps
- Navigate to the Releases page
- Select the version you want to download
- Choose the binary for your operating system
- Verify the SHA-256 or SHA-512 checksum after download (recommended)
- Install and run the application
Verifying Downloads
Each binary includes SHA-256 (hex) and SHA-512 (Base64) hashes for verification. Compare the hash after downloading:
Get-FileHash -Algorithm SHA256 .\your-app-setup.exe
Auto-Update Setup
Configure your Electron app to automatically check for and install updates using electron-updater.
1. Install Dependencies
npm install electron-updater
2. Configure electron-builder
Add the following configuration to your electron-builder.json or package.json:
{"build": {"appId": "com.yourcompany.yourapp","publish": {"provider": "generic","url": "https://YOUR_DOMAIN/api/update"}}}
3. Main Process Configuration
Add the auto-updater logic to your main process file. The platform and channel parameters are sent automatically:
1// main.ts or main.js2import { app, BrowserWindow, ipcMain } from 'electron'3import { autoUpdater } from 'electron-updater'4import log from 'electron-log'5import * as os from 'os'67// Configure logging8autoUpdater.logger = log9autoUpdater.logger.transports.file.level = 'info'1011// Map Node.js platform to electron-updater format12const platformMap = {13 win32: 'win32',14 darwin: 'darwin',15 linux: 'linux'16}1718// Configure update server with explicit platform and channel parameters19autoUpdater.setFeedURL({20 provider: 'generic',21 url: `https://YOUR_DOMAIN/api/update?platform=${platformMap[os.platform()] || 'win32'}`,22 channel: 'stable' // or 'beta', 'alpha'23})2425// Disable auto-download (optional - for manual control)26autoUpdater.autoDownload = false2728// Check for updates on app start29app.whenReady().then(() => {30 // Check for updates after 3 seconds31 setTimeout(() => {32 autoUpdater.checkForUpdates()33 }, 3000)34})3536// Auto-updater events37autoUpdater.on('checking-for-update', () => {38 log.info('Checking for updates...')39})4041autoUpdater.on('update-available', (info) => {42 log.info('Update available:', info.version)43 // Notify renderer process44 mainWindow?.webContents.send('update-available', info)45})4647autoUpdater.on('update-not-available', () => {48 log.info('No updates available')49})5051autoUpdater.on('download-progress', (progress) => {52 log.info(`Download progress: ${progress.percent.toFixed(1)}%`)53 mainWindow?.webContents.send('download-progress', progress)54})5556autoUpdater.on('update-downloaded', (info) => {57 log.info('Update downloaded')58 mainWindow?.webContents.send('update-downloaded', info)59})6061autoUpdater.on('error', (error) => {62 log.error('Auto-updater error:', error)63})6465// IPC handlers for renderer process control66ipcMain.handle('check-for-updates', () => {67 return autoUpdater.checkForUpdates()68})6970ipcMain.handle('download-update', () => {71 return autoUpdater.downloadUpdate()72})7374ipcMain.handle('install-update', () => {75 autoUpdater.quitAndInstall(false, true)76})
4. Renderer Process (React Example)
1// UpdateNotification.tsx2import { useEffect, useState } from 'react'34interface UpdateInfo {5 version: string6 releaseNotes: string7}89export function UpdateNotification() {10 const [updateAvailable, setUpdateAvailable] = useState(false)11 const [updateInfo, setUpdateInfo] = useState<UpdateInfo | null>(null)12 const [downloadProgress, setDownloadProgress] = useState(0)13 const [isDownloading, setIsDownloading] = useState(false)14 const [isDownloaded, setIsDownloaded] = useState(false)1516 useEffect(() => {17 // Listen for update events from main process18 window.electron.onUpdateAvailable((info: UpdateInfo) => {19 setUpdateAvailable(true)20 setUpdateInfo(info)21 })2223 window.electron.onDownloadProgress((progress: { percent: number }) => {24 setDownloadProgress(progress.percent)25 })2627 window.electron.onUpdateDownloaded(() => {28 setIsDownloading(false)29 setIsDownloaded(true)30 })31 }, [])3233 const handleDownload = async () => {34 setIsDownloading(true)35 await window.electron.downloadUpdate()36 }3738 const handleInstall = () => {39 window.electron.installUpdate()40 }4142 if (!updateAvailable) return null4344 return (45 <div className="update-notification">46 <h3>Update Available</h3>47 <p>Version {updateInfo?.version} is available</p>4849 {isDownloading && (50 <div className="progress-bar">51 <div style={{ width: `${downloadProgress}%` }} />52 <span>{downloadProgress.toFixed(1)}%</span>53 </div>54 )}5556 <div className="actions">57 {!isDownloaded ? (58 <button onClick={handleDownload} disabled={isDownloading}>59 {isDownloading ? 'Downloading...' : 'Download'}60 </button>61 ) : (62 <button onClick={handleInstall}>63 Install & Restart64 </button>65 )}66 </div>67 </div>68 )69}
API Reference
Complete reference for all available API endpoints.
/api/releasesQuery Parameters
| Parameter | Type | Description |
|---|---|---|
channel | string | Filter by channel (stable, beta, alpha) |
limit | number | Number of results (default: 10) |
offset | number | Pagination offset (default: 0) |
Example Response
{"releases": [{"version": "2.1.0","channel": "stable","changelog": "## What's New\n- Feature A\n- Bug fixes","tags": ["breaking"],"publishedAt": "2024-01-15T10:30:00Z","binaries": [{"platform": "win32","filename": "app-2.1.0-setup.exe","size": 85234567,"sha256": "a1b2c3d4e5...","sha512": "XYZ123abc..."}]}],"total": 25}
/api/releases/:versionPath Parameters
| Parameter | Type | Description |
|---|---|---|
version | string | Semver version (e.g., 2.1.0, 1.0.0-beta.1) |
Example Request
curl https://YOUR_DOMAIN/api/releases/2.1.0
/api/update/latest.ymlQuery Parameters
| Parameter | Type | Description |
|---|---|---|
platform | string | Optional: win32, darwin, or linux (auto-detected from User-Agent if not provided) |
channel | string | Optional: stable (default), beta, alpha |
Example Request
curl "https://YOUR_DOMAIN/api/update/latest.yml?platform=win32&channel=stable"
Example Response
version: 2.1.0files:- url: app-2.1.0-setup.exesha512: abc123...size: 85234567path: app-2.1.0-setup.exesha512: abc123...releaseDate: '2024-01-15T10:30:00Z'releaseNotes: |## What's New- Feature A- Bug fixes
Note: This is the primary endpoint used by electron-updater. The platform parameter should be sent explicitly in the URL for reliable detection.
Release Channels
Use release channels to distribute different versions to different user groups.
// Configure channel in electron-updaterautoUpdater.channel = 'beta' // Switch to beta channel// Or set via feed URLautoUpdater.setFeedURL({provider: 'generic',url: 'https://YOUR_DOMAIN/api/update/latest?channel=beta'})
Integrity Verification
All binaries include both SHA-256 and SHA-512 checksums for integrity verification. Electron-updater automatically validates downloads using SHA-512 in Base64 format.
Note: The platform uses SHA-512 in Base64 format for electron-updater compatibility, and SHA-256 in hexadecimal for manual verification.
Manual SHA-256 Verification
1// Verify download integrity using SHA-256 (manual verification)2import crypto from 'crypto'3import fs from 'fs'45async function verifySHA256(filePath: string, expectedHash: string): Promise<boolean> {6 return new Promise((resolve, reject) => {7 const hash = crypto.createHash('sha256')8 const stream = fs.createReadStream(filePath)910 stream.on('data', (data) => hash.update(data))11 stream.on('end', () => {12 const calculatedHash = hash.digest('hex')13 resolve(calculatedHash === expectedHash)14 })15 stream.on('error', reject)16 })17}1819// Usage20const isValid = await verifySHA256('./app-setup.exe', 'expected-sha256-hash-in-hex')21if (!isValid) {22 throw new Error('File integrity check failed!')23}
SHA-512 Verification (electron-updater format)
1// Verify using SHA-512 in Base64 (same format as electron-updater)2import crypto from 'crypto'3import fs from 'fs'45async function verifySHA512Base64(filePath: string, expectedHash: string): Promise<boolean> {6 return new Promise((resolve, reject) => {7 const hash = crypto.createHash('sha512')8 const stream = fs.createReadStream(filePath)910 stream.on('data', (data) => hash.update(data))11 stream.on('end', () => {12 const calculatedHash = hash.digest('base64')13 resolve(calculatedHash === expectedHash)14 })15 stream.on('error', reject)16 })17}1819// Usage20const isValid = await verifySHA512Base64('./app-setup.exe', 'expected-sha512-base64')21if (!isValid) {22 throw new Error('SHA-512 integrity check failed!')23}
Tip: electron-updater performs SHA-512 verification automatically. Manual verification is only needed if downloading files outside the auto-update flow.
Troubleshooting
Common issues and their solutions.
Ensure your app has internet access and the update server URL is correct.
// Enable detailed loggingimport log from 'electron-log'autoUpdater.logger = logautoUpdater.logger.transports.file.level = 'debug'
On Windows, ensure the app is code-signed. On macOS, check Gatekeeper settings.
// Force quit and installautoUpdater.quitAndInstall(false, // isSilenttrue // isForceRunAfter)
The update server should return proper CORS headers. Check your server configuration.
{"headers": {"Access-Control-Allow-Origin": "*","Access-Control-Allow-Methods": "GET, OPTIONS"}}