Primeros pasos con Electron Updater

Esta guía te explica cómo configurar @capgo/electron-updater en tu aplicación Electron para habilitar actualizaciones en vivo de JavaScript/HTML/CSS.

Consejo

¿Ya usas Capgo con Capacitor? Electron Updater usa el mismo backend de Capgo Cloud, así que puedes gestionar apps móviles y de escritorio desde el mismo dashboard.

Requisitos

• Electron 20.0.0 o superior
• Node.js 18 o superior
• Una cuenta de Capgo (regístrate en capgo.app)

Instalación

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

1. Instala el paquete:

   npm install @capgo/electron-updater

2. Obtén tu App ID desde el dashboard de Capgo. Si aún no has creado una app, ejecuta:

   npx @capgo/cli@latest init

Inicio rápido

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

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

Errores comunes

• Llama a notifyAppReady() al inicio del arranque —dentro del timeout configurado— antes de la inicialización lenta de la UI.
• Iguala la firma de Capgo en el proceso principal.
• Set update channels before shipping.

Configuración

El Electron Updater requiere configuración en tres lugares: el proceso principal, el script de precarga y el proceso renderer.

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

preload.ts

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

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

Proceso renderer

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

Precaución

Usted usar llamar notifyAppReady() en 10 segundos tras el inicio de la app (configurable mediante appReadyTimeout). Si no se llama, el actualizador asume que la actualización falló y revierte a la versión anterior.

Comprobando actualizaciones

Con autoUpdate: true, el updater comprueba automáticamente si hay actualizaciones. También puedes iniciar comprobaciones manuales:

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

Escuchando eventos

Sigue el progreso y estado de las actualizaciones mediante eventos:

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

Desplegando actualizaciones

Usa el Capgo CLI para subir actualizaciones:

# Build your app
npm run build

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

Tu app de Electron detectará y descargará automáticamente el nuevo bundle en la próxima comprobación.

Menú de depuración

Habilita el menú de depuración durante el desarrollo:

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

Presiona Ctrl+Shift+D (o Cmd+Shift+D en Mac) para abrir el menú de depuración y:

• Ver información del bundle actual
• Cambiar entre los bundles disponibles
• Restablecer a la versión integrada
• Ver información del dispositivo y del canal

Opciones de configuración

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)
});

Próximos pasos

• Referencia de API - Explora todos los métodos disponibles
• Canales - Aprende sobre los canales de despliegue
• Reversiones - Entiende la protección contra rollback

Continúa desde Getting Started with Electron Updater

Si estás usando Primeros pasos con Electron Updater para planificar el trabajo con plugins nativos, conéctalo con Uso de @capgo/electron-updater para la funcionalidad nativa en Uso de @capgo/electron-updater, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.