@todesktop/runtime

@todesktop/runtime

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

• Installation
• Minimal Usage
• Default Behaviour
• API
• Events
• Recipes
• Debugging
• More documentation

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)
• .autoUpdater.checkForUpdates(options)
• .autoUpdater.on(eventName, callback)
• .autoUpdater.restartAndInstall()

.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.

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.

More documentation

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