DOCSEARCHbyAlgolia
Submit Docs

update-electron-app

repository·main·Indexed 21 days ago

https://github.com/electron/update-electron-app

A drop-in module that adds auto-updating capabilities to Electron applications on macOS and Windows. It supports the free update.electronjs.org service via GitHub repositories or custom static file storage (e.g., S3). The module provides configurable update intervals, custom logging, and user notification dialogs for applying updates.

Tokens
2.2K
Snippets
8
Records
12
Agent score
24%

What's inside update-electron-app

  1. Build assets required for auto-updates

    main

    To ensure auto-updates work, you must build the correct assets for each platform:

    macOS

    • Build a .zip file (e.g., using electron-forge or electron-installer-zip).

    Windows

    • Build a .exe and .nupkg files (e.g., using electron-forge or electron-winstaller).
    • Crucial: For Squirrel.Windows updates, every GitHub Release must include:
      • RELEASES (the manifest file)
      • *-full.nupkg (the full update package)
      • *.exe (the installer)
      • *-delta.nupkg (optional, for smaller delta updates)

  3. Requirements for using update-electron-app

    main

    Before integrating this module, ensure your app meets these criteria:

    • Platforms: Your app must run on macOS or Windows.
    • Code Signing: Builds must be code signed (macOS only).
    • If using update.electronjs.org:
      • Your app must have a public GitHub repository.
      • Your builds must be published to GitHub Releases.
    • If using static file storage:
      • Your builds must be published to S3 or a similar static file host (e.g., using @electron-forge/publisher-s3).

  4. Configure Update Sources

    main

    You can specify how updates are fetched using the updateSource property in the options object. There are two supported types:

    Electron Public Update Service

    Uses https://update.electronjs.org to host updates based on your GitHub repository.

    • type: UpdateSourceType.ElectronPublicUpdateService
    • repo: A GitHub repository in the format owner/repo. If not provided, it attempts to guess it from your package.json's repository field.
    • host: The base HTTPS URL of the update server. Defaults to https://update.electronjs.org.

    Static Storage

    Uses a custom URL where your update assets are hosted.

    • type: UpdateSourceType.StaticStorage
    • baseUrl: The base HTTPS URL for your static storage provider.
      • Note: On macOS (darwin), the library automatically appends /RELEASES.json to the baseUrl and uses json server type.
    // Example: Using Static Storage
updateElectronApp({
  updateSource: {
    type: UpdateSourceType.StaticStorage,
    baseUrl: 'https://my-updates.example.com/app-updates/'
  }
});

  6. Use static file storage for auto-updates

    main

    To host your own update files (e.g., on S3 or Google Cloud Storage), set the updateSource type to UpdateSourceType.StaticStorage and provide a baseUrl. The module expects a specific file structure: **/{platform}/{arch}/{artifact}.

    const { updateElectronApp, UpdateSourceType } = require('update-electron-app')

updateElectronApp({
  updateSource: {
    type: UpdateSourceType.StaticStorage,
    baseUrl: `https://my-bucket.s3.amazonaws.com/my-app-updates/${process.platform}/${process.arch}`
  }
})

  7. Use update.electronjs.org for auto-updates

    main

    To use the free and open-source update.electronjs.org service, drop updateElectronApp() into your main process. By default, it attempts to find your repository URL from your app's package.json file.

    If you need to specify a custom repository or configuration, use the options object.

    const { updateElectronApp, UpdateSourceType } = require('update-electron-app')

// Default usage (uses repo from package.json)
updateElectronApp()

// Custom configuration
updateElectronApp({
  updateSource: {
    type: UpdateSourceType.ElectronPublicUpdateService,
    repo: 'github-user/repo'
  },
  updateInterval: '1 hour',
  logger: require('electron-log')
})

  8. Configure updateElectronApp options

    main

    The updateElectronApp(options) function accepts the following configuration options:

    • updateInterval (String, optional): How frequently to check for updates. Defaults to 10 minutes. Minimum allowed interval is 5 minutes. Uses human-readable strings supported by the ms module (e.g., '1 hour').
    • logger (Object, optional): A custom logger object that defines a log function. Defaults to console.
    • notifyUser (Boolean, optional): Defaults to true. When enabled, the user is prompted to apply the update immediately after download.

  9. Stop periodic update checks

    main

    The updateElectronApp function returns an object containing a stopUpdates function. Calling this function stops the periodic update checks. It is safe to call at any time, including before the app is ready or on unsupported platforms.

    const { updateElectronApp } = require('update-electron-app')
const { stopUpdates } = updateElectronApp()

// Later, when you no longer want to check for updates:
stopUpdates()

  10. Customize the update notification dialog

    main

    If notifyUser is enabled, the library shows a dialog when an update is downloaded. You can replace the default behavior using onNotifyUser or customize the text using makeUserNotifier().

    Using onNotifyUser callback

    Pass a function to onNotifyUser in the options. This function receives an IUpdateInfo object containing:

    • event: The Electron event.
    • releaseNotes: String of release notes.
    • releaseName: Name of the release.
    • releaseDate: Date of the release.
    • updateURL: URL of the update.

    Using makeUserNotifier

    To keep the default dialog behavior but change the text (title, buttons, etc.), use makeUserNotifier(dialogProps) and pass the result to onNotifyUser.

    dialogProps can include:

    • title: Dialog title (default: 'Application Update').
    • detail: Dialog body text (default: 'A new version has been downloaded...').
    • restartButtonText: Text for the restart button (default: 'Restart').
    • laterButtonText: Text for the later button (default: 'Later').
    import { updateElectronApp, makeUserNotifier } from 'update-electron-app';

updateElectronApp({
  onNotifyUser: makeUserNotifier({
    title: 'Update Available!',
    restartButtonText: 'Install Now'
  })
});

  11. Initialize auto-updates with updateElectronApp()

    main

    Call updateElectronApp() in your Electron main process to start periodic update checks. The function returns an object with a stopUpdates() method to cancel the scheduled checks.

    Note: Updates are automatically aborted if the app is not packaged (app.isPackaged is false). The library currently supports darwin and win32 platforms.

    import { updateElectronApp } from 'update-electron-app';

const updater = updateElectronApp({
  // options
});

// Later, if you need to stop checking for updates:
// updater.stopUpdates();

  12. Define a custom logger

    main

    If you want to redirect update logs to a specific service (like electron-log), provide an object implementing the ILogger interface to the logger option.

    import { updateElectronApp, ILogger } from 'update-electron-app';

const myLogger: ILogger = {
  log: (msg) => console.log(`[LOG] ${msg}`),
  info: (msg) => console.info(`[INFO] ${msg}`),
  error: (msg) => console.error(`[ERROR] ${msg}`),
  warn: (msg) => console.warn(`[WARN] ${msg}`),
};

updateElectronApp({ logger: myLogger });