or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-update-electron-app

A drop-in module that adds autoUpdating capabilities to Electron apps

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/update-electron-app@3.1.x

To install, run

npx @tessl/cli install tessl/npm-update-electron-app@3.1.0

index.mddocs/

Update Electron App

Update Electron App is a drop-in module that adds autoUpdating capabilities to Electron applications. It provides seamless integration with minimal configuration, supporting multiple update sources including the free update.electronjs.org service and static file storage solutions like S3.

Package Information

  • Package Name: update-electron-app
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install update-electron-app

Core Imports

import { updateElectronApp, makeUserNotifier, UpdateSourceType } from "update-electron-app";

For CommonJS:

const { updateElectronApp, makeUserNotifier, UpdateSourceType } = require("update-electron-app");

Note: This package is designed for use within Electron applications, so Electron types (like Electron.Event) are available in the runtime environment.

Basic Usage

import { updateElectronApp, UpdateSourceType } from "update-electron-app";

// Simple setup with default configuration
updateElectronApp();

// Custom configuration with update.electronjs.org
updateElectronApp({
  updateSource: {
    type: UpdateSourceType.ElectronPublicUpdateService,
    repo: 'owner/repo'
  },
  updateInterval: '1 hour',
  notifyUser: true
});

// Static storage configuration
updateElectronApp({
  updateSource: {
    type: UpdateSourceType.StaticStorage,
    baseUrl: 'https://my-bucket.s3.amazonaws.com/my-app-updates'
  }
});

Architecture

Update Electron App is built around several key components:

  • Update Sources: Supports both Electron's public update service and static file storage
  • Automatic Checking: Configurable intervals for checking updates (minimum 5 minutes)
  • Background Downloads: Downloads updates without blocking the application
  • User Notifications: Customizable dialogs to prompt users about available updates
  • Platform Detection: Automatically handles macOS (.zip) and Windows (.exe/.nupkg) update formats
  • Error Handling: Comprehensive error handling and logging capabilities

Capabilities

Auto-Update Management

Main function to enable auto-updating for Electron applications.

/**
 * Enables auto-updating for Electron applications
 * @param opts - Configuration options for the updater
 */
function updateElectronApp(opts: IUpdateElectronAppOptions = {}): void;

interface IUpdateElectronAppOptions<L = ILogger> {
  /** @deprecated Use updateSource instead */
  readonly repo?: string;
  /** @deprecated Use updateSource instead */
  readonly host?: string;
  /** Update source configuration */
  readonly updateSource?: IUpdateSource;
  /** How frequently to check for updates. Defaults to '10 minutes'. Minimum allowed is '5 minutes' */
  readonly updateInterval?: string;
  /** Custom logger object. Defaults to console */
  readonly logger?: L;
  /** Whether to notify user when updates are available. Defaults to true */
  readonly notifyUser?: boolean;
  /** Custom callback for user notification. Only runs if notifyUser is true */
  readonly onNotifyUser?: (info: IUpdateInfo) => void;
}

User Notification

Helper function to create customizable user notification dialogs.

/**
 * Creates a callback function for customizing user notification dialogs
 * @param dialogProps - Customizable text for the dialog
 * @returns Callback function for handling update notifications
 */
function makeUserNotifier(dialogProps?: IUpdateDialogStrings): (info: IUpdateInfo) => void;

interface IUpdateDialogStrings {
  /** Dialog title. Defaults to 'Application Update' */
  title?: string;
  /** Dialog message. Defaults to 'A new version has been downloaded. Restart the application to apply the updates.' */
  detail?: string;
  /** Restart button text. Defaults to 'Restart' */
  restartButtonText?: string;
  /** Later button text. Defaults to 'Later' */
  laterButtonText?: string;
}

Update Sources

Configuration for different update source types.

enum UpdateSourceType {
  ElectronPublicUpdateService,
  StaticStorage
}

interface IElectronUpdateServiceSource {
  type: UpdateSourceType.ElectronPublicUpdateService;
  /** GitHub repository in format 'owner/repo'. Defaults to package.json repository field */
  repo?: string;
  /** Base HTTPS URL of update server. Defaults to 'https://update.electronjs.org' */
  host?: string;
}

interface IStaticUpdateSource {
  type: UpdateSourceType.StaticStorage;
  /** Base URL for static storage provider where updates are stored */
  baseUrl: string;
}

type IUpdateSource = IElectronUpdateServiceSource | IStaticUpdateSource;

Update Information

Data structures for update information and logging.

interface IUpdateInfo {
  event: Electron.Event;
  releaseNotes: string;
  releaseName: string;
  releaseDate: Date;
  updateURL: string;
}

interface ILogger {
  log(message: string): void;
  info(message: string): void;
  error(message: string): void;
  warn(message: string): void;
}

Platform Support

  • Supported Platforms: macOS (darwin), Windows (win32)
  • Unsupported Platforms: Linux and other platforms (will log warning and exit early)

Requirements

  • Electron application running on macOS or Windows
  • For update.electronjs.org: Public GitHub repository with releases published to GitHub Releases
  • For static storage: Updates published to S3 or similar static file host
  • Code signing required for macOS applications

Update Process

  1. App checks for updates at startup and at configured intervals
  2. If update found, downloads automatically in background
  3. When download completes, shows user notification dialog (if enabled)
  4. User can choose to restart immediately or later
  5. On restart, update is applied automatically

Error Handling

The library handles various error conditions:

  • Network connectivity issues during update checks
  • Invalid repository configurations
  • Unsupported platforms
  • File download failures
  • All errors are logged through the configured logger