Primeros pasos: JS / Electron

Applies to

Windows

MacOS

Linux

Comienza con nuestro paquete NPM para JS & Electron.

tip

Esta guía asume que estás creando una aplicación Electron con Electron Forge y el empaquetador Webpack, que es la configuración recomendada. Dado que Velopack contiene un módulo binario nativo (.node), funciona directamente con Webpack. Para crear un proyecto completamente nuevo, puedes usar la plantilla oficial de electron forge:

npm init electron-app@latest my-new-app-name -- --template=webpack-typescript

Usando Vite / Rollup

Velopack también funciona con los empaquetadores vite y rollup, pero debes evitar que empaqueten el módulo nativo .node. Externaliza electron y todas las dependencias de tu package.json para que se carguen desde node_modules en tiempo de ejecución en lugar de ser incluidas en línea:

// vite.config.js
import fs from 'node:fs';
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));

export default defineConfig({
    build: {
        rollupOptions: {
            external: ['electron', ...Object.keys(pkg.dependencies || {})],
        },
    },
});

nota

Algunos usuarios han reportado un error invalid peer certificate: UnknownIssuer de checkForUpdatesAsync al ejecutarse bajo vite/rollup. Este es un problema conocido. No lo soluciones sirviendo actualizaciones sobre http plano — mantén tu fuente de actualizaciones en https y asegúrate de que el almacén de confianza del sistema esté disponible para la aplicación empaquetada.

Agrega Velopack a tu package.json:

npm install velopack

Agrega el siguiente código a tu punto de entrada (p. ej., index.ts) lo antes posible (antes de cualquier otro código de inicio de electron, etc.):

const { VelopackApp } = require('velopack');

// Velopack builder needs to be the first thing to run in the main process.
// In some cases, it might quit/restart the process to perform tasks.
VelopackApp.build().run();

// ... your other app startup code here

Squirrel Startup Code

Si actualmente tienes algún código de inicio de "Squirrel", debes eliminarlo ahora. Por ejemplo:

npm uninstall electron-squirrel-startup @electron-forge/maker-squirrel

Esto tiene cierta complejidad debido al modelo IPC de Electron y a que Velopack tiene un módulo nativo de node.

Primero, debes configurar los manejadores IPC en el hilo principal de tu aplicación. La updateUrl apunta a donde alojes tus actualizaciones (un servidor web, un bucket de S3, lanzamientos de GitHub, etc.):

const { VelopackApp, UpdateManager } = require('velopack');

const updateUrl = "https://the.place/you-host/updates";

ipcMain.handle("velopack:get-version", () => {
    try {
        const updateManager = new UpdateManager(updateUrl);
        return updateManager.getCurrentVersion();
    } catch (e) {
        return `Not Installed (${e})`;
    }
});

ipcMain.handle("velopack:check-for-update", async () => {
    const updateManager = new UpdateManager(updateUrl);
    return await updateManager.checkForUpdatesAsync();
});

ipcMain.handle("velopack:download-update", async (_, updateInfo) => {
    const updateManager = new UpdateManager(updateUrl);
    await updateManager.downloadUpdateAsync(updateInfo);
    return true;
});

ipcMain.handle("velopack:apply-update", async (_, updateInfo) => {
    const updateManager = new UpdateManager(updateUrl);
    await updateManager.waitExitThenApplyUpdate(updateInfo);
    app.quit();
    return true;
});

A diferencia de los SDKs de C# y Python, el enlace JS no tiene un único asistente de aplicar-y-reiniciar, por lo que llamas a waitExitThenApplyUpdate (que prepara el actualizador y espera a que este proceso termine) y luego sales de la aplicación tú mismo mediante app.quit().

A continuación, debes exponer estas funciones a tus procesos de renderizado en preload.ts

import { contextBridge, ipcRenderer } from "electron";
import type { UpdateInfo } from "velopack";

interface VelopackBridgeApi {
    getVersion: () => Promise<string>,
    checkForUpdates: () => Promise<UpdateInfo>,
    downloadUpdates: (updateInfo: UpdateInfo) => Promise<boolean>,
    applyUpdates: (updateInfo: UpdateInfo) => Promise<boolean>,
}

declare global {
    interface Window {
        velopackApi: VelopackBridgeApi;
    }
}

const velopackApi: VelopackBridgeApi = {
    getVersion: () => ipcRenderer.invoke("velopack:get-version"),
    checkForUpdates: () => ipcRenderer.invoke("velopack:check-for-update"),
    downloadUpdates: (updateInfo: UpdateInfo) => ipcRenderer.invoke("velopack:download-update", updateInfo),
    applyUpdates: (updateInfo: UpdateInfo) => ipcRenderer.invoke("velopack:apply-update", updateInfo)
};

contextBridge.exposeInMainWorld("velopackApi", velopackApi);

Por último, ahora puedes usar estas funciones en tu renderizador para proporcionar una interfaz de actualización a tus usuarios:

async function updateApp() {
    // check for new version
    const updateInfo = await window.velopackApi.checkForUpdates();
    if (!updateInfo) {
        return; // no updates available
    }

    // download new version
    await window.velopackApi.downloadUpdates(updateInfo);

    // install new version and restart app
    await window.velopackApi.applyUpdates(updateInfo);
}

Compila tu aplicación a un binario (p. ej., .exe en Windows). Ejemplo usando electron forge:

npx electron-forge package

Velopack usa una herramienta de línea de comandos llamada vpk para empaquetar y publicar versiones. Se distribuye como una herramienta global de .NET. Aunque Velopack puede usarse con aplicaciones escritas en varios lenguajes, se requiere el SDK de .NET para instalar y ejecutar vpk. Puedes instalar el SDK de .NET desde la página de descarga de .NET.

Una vez instalado .NET, puedes instalar vpk ejecutando:

dotnet tool install -g vpk

tip

Se recomienda usar la misma versión de vpk que el paquete Velopack referenciado en tu aplicación para garantizar la compatibilidad.

Alternativamente, puedes ejecutar vpk sin instalarlo globalmente usando el comando dnx. Usa la sintaxis @<version> para fijar la versión de la herramienta vpk:

dnx vpk@1.0.0

Reemplaza 1.0.0 con la versión del paquete Velopack que estás usando en tu aplicación.

Ahora estás listo para crear una versión de Velopack para tu aplicación.

El --packId puede ser cualquier identificador de aplicación único que desees utilizar. Dado que debe ser único entre todas las aplicaciones, recomendamos incluir el nombre de tu empresa: <CompanyName>.<AppName>.

La opción --mainExe solo es necesaria si el nombre de tu ejecutable es diferente al --packId de tu aplicación.

Consulta la referencia de CLI para obtener más detalles sobre las opciones disponibles.

vpk pack --packId YourAppId --packVersion 1.0.0 --packDir .\publish --mainExe yourMainApp.exe

✅ ¡Listo! Tu aplicación ahora tiene actualizaciones automáticas y un instalador. Puedes subir tu release a tu sitio web, o usar el comando vpk upload para publicarla en el destino que elijas.

También puedes consultar nuestras Aplicaciones de ejemplo para ver ejemplos completos que usan Velopack.

Usando Vite / Rollup​

Usando Vite / Rollup