Nickel Palladium Manganese

    @todesktop/runtime
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    @todesktop/runtime

    The ToDesktop runtime package which takes care of auto-updating, crash reporting, and more. For more information, see https://todesktop.com/cli.

    Important

    If you are using this library with Electron 11 or earlier then please use version 0.6.5.

    If you are using Electron 12 or later then you can use version 1.0.0 or later.

    Table of contents

    Installation

    Via npm:

    npm install @todesktop/runtime

    Or Yarn:

    yarn add @todesktop/runtime

    Minimal usage

    In your main (background process) script, require the package and call the init function. The key is to call it right at the beginning. We'll do the rest.

    const { app, BrowserWindow } = require("electron");
    const todesktop = require("@todesktop/runtime");
    
    todesktop.init();
    
    function createWindow() {
      // Create the browser window.
      let win = new BrowserWindow({
        width: 800,
        height: 600,
        webPreferences: {
          nodeIntegration: true,
        },
      });
    
      // and load the index.html of the app.
      win.loadFile("index.html");
    }
    
    app.whenReady().then(createWindow);

    Check out todesktop-quick-start to see a minimal example project.

    Also, see the full API below to learn more about the other methods and events.

    Default behaviour

    By default, we check for updates when the app launches and every 10 minutes thereafter.

    When an update is found, we show a notification explaining that an update has been downloaded and once they exit/restart, it'll be installed. Your user doesn't have to accept any prompt or anything like that. Only one notification is shown, max.

    This default behaviour can be augmented using the API below, e.g. if you want to offer your users a button to check for updates, a prompt to restart and install the update, etc.

    Disabling the default auto-update behaviour

    It's also possible to disable some or all of the default behaviour.

    What happens when an update is found can be disabled using the update-downloaded event (learn more below).

    Everything (the notification, the auto-checks on launch and on interval) can be disabled by passing autoUpdater: false to the .init method (learn more below).

    API

    .init(options)

    This initializes ToDesktop. You must call this at the top of your main script. If the app isn't packaged, this won't do much. .autoUpdater.checkForUpdates will never check or find an update, for example.

    Returns nothing.

    options (Optional)

    Type: object

    Default: { autoUpdater: true }

    options.autoUpdater (Optional)

    Type: boolean

    Default: true

    If false, this will disable all of the default auto-update behaviour. I.e. it will not auto-check on launch, on interval, or show a notification when an update is found. The events will always be fired.

    If you do this, everything is in your hands. You must manually call .autoUpdater.checkForUpdates or else your users will never get an update.

    options.customLogger (Optional)

    Default: undefined

    To debug, you can pass a custom logger object. You can pass electron-log (recommended), winston, or another logger with the following interface: { error(), info(), warn() }. Include a debug() method to get even more information.

    Example using electron-log:

    const electronLog = require("electron-log");
    const todesktop = require("@todesktop/runtime");
    
    electronLog.transports.file.level = "debug";
    todesktop.init({
      customLogger: electronLog,
    });

    .autoUpdater.checkForUpdates(options)

    This performs a check for updates and downloads it. Only call this after the application is ready.

    It returns a Promise which resolves to an object.

    If there is no update available, the result will be { updateInfo: null }.

    If there is an update available, the result will look like this:

    {
      updateInfo: {
        releaseDate: "2011-10-05T14:48:00.000Z",
        version: "2.0.1",
      }
    }

    This method can reject with an error, e.g. if the network is unstable.

    options (Optional)

    Type: object

    Default: { source: "programmatic-call" }

    options.source (Optional)

    Type: string

    Default: "programmatic-call"

    The source/trigger of the update check. The update-downloaded event passes this back to you so you can identify the source(s) of the update check.

    Example

    try {
      const result = await todesktop.autoUpdater.checkForUpdates();
      if (result.updateInfo) {
        console.log("Update found:", result.updateInfo.version);
        todesktop.autoUpdater.restartAndInstall();
      }
    } catch (e) {
      console.log("Update check failed:", e);
    }

    .autoUpdater.on(eventName, callback)

    This subscribes to an event. The callback will be called when the event occurs.

    .autoUpdater is an instance of EventEmitter2 so it supports all of the same methods; e.g. .once, .off, and so on.

    eventName

    Type: string

    callback

    Type: Function

    .autoUpdater.restartAndInstall()

    This restarts the application and installs the new update after one has been found.

    Returns nothing.

    NOTE: this method will close all application windows first and only emit before-quit event on app after that. This is different from the normal quit event sequence. However, this is not the case if the method is called from a Squirrel.Windows application.

    Events

    before-quit-for-update

    This is the same as Electron's before-quit-for-update auto-updater event.

    checking-for-update

    Emitted when checking if an update has started.

    update-available

    Emitted when there is an available update. Callback contains the following object:

    {
      releaseDate: "2011-10-05T14:48:00.000Z",
      version: "2.1.3"
    }

    update-not-available

    Emitted when there is no available update. Callback contains the following object:

    {
      releaseDate: "2011-10-05T14:48:00.000Z",
      version: "2.1.3"
    }

    download-progress

    Emitted on progress. Callback contains the following object:

    • progress
    • bytesPerSecond
    • percent
    • total
    • transferred

    update-downloaded

    Emitted when there is an update available and downloaded. The update has already been downloaded.

    Your callback is called with an object like this:

    {
      sources: ["auto-check-on-interval"],
      updateInfo: {
        releaseDate: "2011-10-05T14:48:00.000Z",
        version: "2.1.3"
      }
    }

    sources (an array of strings) are the sources/triggers of the update check. The default built-in sources are auto-check-on-launch, auto-check-on-interval, and programmatic-call. You can pass a custom source to .autoUpdater.checkForUpdates. NOTE: sources is an array because multiple checks could be triggered around the same time. They do not cancel an existing update check but piggyback onto it instead.

    By default, we show a notification explaining that an update has been downloaded and once they exit/restart, it'll be installed. Your user doesn't have to accept any prompt or anything like that. Only one notification is shown, max.

    To disable this, you can return false (or a Promise which resolves to promise). If your callback errors or it returns a Promise that doesn't resolve within 500 milliseconds, the default behaviour will proceed.

    Example

    todesktop.autoUpdater.on("update-downloaded", (event) => {
      console.log("Update found:", event.updateInfo.version);
      if (event.sources.includes("my-custom-source")) {
        return false;
        todesktop.autoUpdater.restartAndInstall();
      }
      // Else: the default behaviour (notification) will happen
    });

    Recipes

    How do I show a message on my UI to indicate that an update is available?

    By default, ToDesktop runtime will show a notification that an update is ready to be installed. However, it is possible that the user may have notifications turned off for your app. For this reason, it's a good idea to notify your users of an update directly on the UI of your app.

    ToDesktop runtime is only available in the main process of Electron. So we need to use IPC to tell the UI that an update is available, let's do that:

    const todesktop = require("@todesktop/runtime");
    const { ipcMain } = require("electron");
    
    todesktop.init();
    
    const win = new BrowserWindow(/* Options here */);
    
    // When we receive an update-downloaded event then
    // we forward that event to our UI using IPC
    todesktop.autoUpdater.on("update-downloaded", (event) => {
      win.webContents.send("update-downloaded", event);
    });
    
    // Listen for the UI to tell us that it wants to
    // do a restart and install of the app
    ipcMain.on("restart-and-install", () => {
      todesktop.autoUpdater.restartAndInstall();
    });

    In our UI we want to show a div when an update is ready to install. Here's the HTML:

    <div class="update-available" style="display:none;">
      Version <span class="app-version"></span> is ready to Install.
      <a href="#" class="click-to-install">
        Click here to restart the app and install the update </a
      >.
    </div>

    Let's hook it all up. We use IPC on the renderer thread to update our UI:

    const { ipcRenderer } = require("electron");
    
    // First let's hook up our click-to-install link
    const installLink = document.querySelector(".click-to-install");
    installLink.addEventListener("click", (e) => {
      e.preventDefault();
      ipcRenderer.send("restart-and-install");
    });
    
    // Now let's listen for updates and show the
    // update-available div on our UI
    const updateAvailableDiv = document.querySelector(".update-available");
    const appVersionSpan = document.querySelector(".app-version");
    ipcRenderer.on("update-downloaded", (e, { updateInfo }) => {
      // Update the version text
      appVersionSpan.innerText = updateInfo.version;
    
      // Show the update-available div
      updateAvailableDiv.style.display = "block";
    });

    How do I force the application to restart when an update has been downloaded?

    First up, make sure that this is something that you want to do. For example, a user might be in the middle of typing a message on your UI when you restart the app.

    If you still want to go ahead then here is a simple recipe to do just that.

    todesktop.autoUpdater.on("update-downloaded", () => {
      // Immediately update the app and restart it
      todesktop.autoUpdater.restartAndInstall();
    
      // Return false so that a notification is not displayed
      return false;
    });

    Debugging

    See the customLogger option.

    Alternatively, set the DEBUG environment variable and the logs will be sent to the main process logs; DEBUG=@todesktop/runtime.

    More documentation

    For documentation on ToDesktop CLI See https://www.npmjs.com/package/@todesktop/cli

    Keywords

    none

    Install

    npm i @todesktop/runtime

    DownloadsWeekly Downloads

    625

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    59.9 kB

    Total Files

    29

    Last publish

    Collaborators

    • sandeep1995
    • davej
    • isaacaderogba