@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

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

Debugging

See the customLogger option.

More documentation

See https://docs.todesktop.com/cli/using-the-todesktop-cli