Démarrer avec Electron Updater

Ce guide vous accompagne pour configurer @capgo/electron-updater dans votre application Electron afin d'activer les live update JavaScript/HTML/CSS.

Astuce

Vous utilisez déjà Capgo avec Capacitor ? L'Electron Updater utilise le même backend Cloud Capgo, vous permettant de gérer vos apps mobiles et desktop depuis le même dashboard.

Prerequisites

• Electron 20.0.0 ou supérieur
• Node.js 18 ou supérieur
• Un compte Capgo (inscrivez-vous sur capgo.app)

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Utilisez ensuite le prompt suivant :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/electron-updater` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin avec les commandes suivantes, puis suivez les instructions spécifiques à chaque plateforme ci-dessous :

1. Installez le package :

   npm install @capgo/electron-updater

2. Récupérez votre App ID depuis le dashboard Capgo. Si vous n'avez pas encore créé d'application, lancez :

   npx @capgo/cli@latest init

Démarrage rapide

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

const updater = requireUpdater();
await updater.notifyAppReady();

Erreurs courantes

• Appelez notifyAppReady() tôt lors du lancement — avant le timeout configuré — avant l'initialisation lente de l'UI.
• Associez la signature Capgo dans le processus principal.
• Set update channels before shipping.

Configuration

L'Electron Updater nécessite une configuration à trois endroits : le processus principal, le script de preload et le processus de rendu.

Processus principal

main.ts

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

// Create updater instance with your Capgo App ID
const updater = new ElectronUpdater({
  appId: 'YOUR_CAPGO_APP_ID', // e.g., 'com.example.myapp'
  autoUpdate: true,
});

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

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

  // Setup IPC communication between main and renderer
  setupIPCHandlers(updater);
  setupEventForwarding(updater, mainWindow);

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

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

Script de preload

preload.ts

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

// Expose the updater API to the renderer process
exposeUpdaterAPI();

Processus de rendu

// renderer.ts (or in your app's entry point)
import { requireUpdater } from '@capgo/electron-updater/renderer';

const updater = requireUpdater();

// CRITICAL: Call this on every app launch!
// This confirms the bundle loaded successfully and prevents rollback
await updater.notifyAppReady();

console.log('App ready, current bundle:', await updater.current());

Attention

Vous devez appeler notifyAppReady() dans les 10 secondes suivant le lancement de l'app (configurable via appReadyTimeout). Si l'appel n'est pas effectué, l'updater considère que la mise à jour a échoué et effectue un rollback vers la version précédente.

Vérification des mises à jour

Avec autoUpdate: true, l'updater vérifie automatiquement les mises à jour. Vous pouvez également déclencher des vérifications manuelles :

// Check for updates manually
const latest = await updater.getLatest();

if (latest.url && !latest.error) {
  console.log('Update available:', latest.version);

  // Download the update
  const bundle = await updater.download({
    url: latest.url,
    version: latest.version,
    checksum: latest.checksum,
  });

  console.log('Downloaded bundle:', bundle.id);

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

  // Option 2: Apply immediately and reload
  // await updater.set({ id: bundle.id });
}

Écoute des événements

Track update progress and status with events:

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

// Update available
updater.addListener('updateAvailable', (event) => {
  console.log('New version available:', event.bundle.version);
});

// Download completed
updater.addListener('downloadComplete', (event) => {
  console.log('Download finished:', event.bundle.id);
});

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

Déploiement des mises à jour

Utilisez Capgo CLI pour envoyer les mises à jour :

# Build your app
npm run build

# Upload to Capgo
npx @capgo/cli@latest bundle upload --channel=production

Votre application Electron détectera et téléchargera automatiquement le nouveau bundle lors de la prochaine vérification.

Menu de debug

Activez le menu de debug pendant le développement :

const updater = new ElectronUpdater({
  appId: 'YOUR_CAPGO_APP_ID',
  debugMenu: true, // Enable debug menu
});

Appuyez sur Ctrl+Shift+D (ou Cmd+Shift+D sur Mac) pour ouvrir le menu de debug et :

• Consulter les infos du bundle actuel
• Basculer entre les bundles disponibles
• Réinitialiser vers la version intégrée
• Voir les infos de l'appareil et du canal

Options de configuration

const updater = new ElectronUpdater({
  // Required
  appId: 'com.example.app',

  // Server URLs (defaults to Capgo Cloud)
  updateUrl: 'https://plugin.capgo.app/updates',
  channelUrl: 'https://plugin.capgo.app/channel_self',
  statsUrl: 'https://plugin.capgo.app/stats',

  // Behavior
  autoUpdate: true,           // Enable auto-updates
  appReadyTimeout: 10000,     // MS before rollback (default: 10s)
  autoDeleteFailed: true,     // Delete failed bundles
  autoDeletePrevious: true,   // Delete old bundles after successful update

  // Channels
  defaultChannel: 'production',

  // Security
  publicKey: '...',           // For end-to-end encryption

  // Debug
  debugMenu: false,           // Enable debug menu
  disableJSLogging: false,    // Disable console logs

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

Étapes suivantes

• Référence API - Explorer toutes les méthodes disponibles
• Canaux - Découvrir les canaux de déploiement
• Rollbacks - Comprendre la protection contre les rollbacks

Continuer après la prise en main d'Electron Updater

Si vous utilisez Démarrer avec Electron Updater pour planifier le travail sur un plugin natif, connectez-l’à Utiliser @capgo/electron-updater pour la capacité native dans l'utilisation de @capgo/electron-updater, Répertoire des plugins Capgo pour le workflow produit dans le répertoire des plugins Capgo, Plugins Capacitor par Capgo pour les détails d'implémentation dans les plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans « Ajouter ou mettre à jour des plugins », et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans les alternatives aux plugins Ionic Enterprise.