Integrate ToDesktop into an electron project

This is a guide for those looking to integrate ToDesktop CLI into an existing Electron project. If you don't have an Electron app, check out todesktop-quick-start for a minimal template project to get you going.

# Drop your old setup

I want to set clear expectations before we start. Once you've migrated and released your app on ToDesktop, you won't need:

• Multiple machines / environments to manually compile binaries.
• To host auto-updates and downloads.
• And so on.

You will just need to call our CLI from one machine and the rest is taken care of.

# Install ToDesktop dependencies

1. Run npm install -g @todesktop/cli.
2. Run npm install --save @todesktop/runtime at the root of your app directory. For now, we'll assume this the same location as your project root. Later, we'll cover projects that have their Electron app in a sub-directory.
3. (Optional) You may also install @todesktop/cli in your project directory (rather than just globally on your machine) for version consistency and CI/CD compatibility. If needed, run: npm install --save-dev @todesktop/cli at the root of your project.

Feel free to use yarn instead.

# Add todesktop.json

Create a todesktop.json file at the root of your project. Here's a minimal example:

        {
  "id": "YOUR-TODESKTOP-ID",
  "icon": "./icon.png",
  "schemaVersion": 1
}

      

• id must contain your application's ToDesktop ID. To find this:
  1. Go to app.todesktop.com
  2. Select your app from the dashboard
  3. Click "Settings" in the nav bar
  4. Your ToDesktop ID will be displayed at the top of the settings page
• icon must point to a PNG or ICNS. This will be used as your app icon.
• schemaVersion is the todesktop.json schema version. This must be 1.

Many other options are supported in todesktop.json. For example, you can have a different icon per OS. Check out the documentation for the full list of options.

# App package.json requirements

Your app's package.json must have the following:

• Electron must be in your devDependencies and it must be a fixed version. I.e. it doesn't start with ^ or ~.
• You must set the author property, e.g. "author" : "Barney Rubble <[email protected]>".

You should also set the productName property. Otherwise, your app name will default to the value of the name property.

# Use @todesktop/runtime in your app

At the top of your app's main script (i.e. in the main process), import @todesktop/runtime and use it;

        const { app, BrowserWindow } = require("electron");
const todesktop = require("@todesktop/runtime");

todesktop.init();

function createWindow() {
  // Create the browser window.
  let win = new BrowserWindow();
  // and load the index.html of the app.
  win.loadFile("index.html");
}

app.whenReady().then(createWindow);

...

      

This handles auto-updates and more for you. The behaviour can be customized. Check out the @todesktop/runtime documentation for the full list of options and methods.

Also, you need to remove any usage of Electron's built-in autoUpdater API, electron-updater, or similar.

# Optional: add npm scripts for releasing your app

It's probably best to add these to add npm scripts to your project's package.json for running ToDesktop builds and releases;

        ...
"scripts": {
  "build": "todesktop build",
  "release": "todesktop release"
},
...

      

For a step-by-step guide on building your app, head here.

# Common questions

# How are dependencies and native modules handled?

The local node_modules you have installed on your machine are not uploaded. Your dependencies are installed on our servers instead. Three times to be exact; once on Linux, Mac, and Windows. It's done this way because your dependencies could have platform-specific postinstall steps, e.g. native modules. It's also faster.

We rebuild your native dependencies against the version of Node.js that your Electron app is using, you don't need any extra config or anything like that.

Also, your devDependencies are excluded from your final app binaries to keep the file size down.

Optional: for local development, using electron-rebuild (in a postinstall script in your app's package.json) will ensure your dependencies are built against the version of Node.js that your Electron project is using.

# What if I need to compile my app code?

If you have a compilation step (e.g. Babel, TypeScript, etc.), that's fine. In general, if you can run your app with the Electron CLI (i.e. electron path/to/app), it will work with ToDesktop.

First, add npm scripts for releasing your app ( as we just covered above). Assuming you already have script for compiling your app like the compile script below, call it in your build and release scripts.

        ...
"scripts": {
  "build": "npm run compile && todesktop build .",
  "compile": "tsc -p .",
  "release": "npm run compile && todesktop build && todesktop release --latest --force",
  "start": "npm run compile && electron ."
},
...

      

# What if my app is in a sub-directory?

If your Electron app is in a sub-directory in your project, you likely have a structure like this:

        .
├── app/
│   ├── package.json
│   ├── main.js
│   ├── index.html
│   └── ...
├── other/
│   └── ...
├── .gitignore
├── ...
├── package.json
├── README.md
└── todesktop.json

      

Here's what you need to know:

• @todesktop/runtime needs to be installed in the app directory, not at the root.
• When adding npm scripts for releasing your app, you need to install @todesktop/cli at the root of your project add the scripts to the root package.json (not in the app directory).
• todesktop.json stays at the root of your project, where you'll be calling the ToDesktop CLI from, but you should set the appPath option to ./app. This is the path to your Electron application directory.

# How can I exclude unnecessary files?

If you have files in your app directory which don't need to be uploaded to our servers or included in your app, you can use the appFiles option in your todesktop.json. This option allows you to decide which files get packed into your app (or not).

For example, use "appFiles": [ "dist/**"] if you want to only include the files in the dist directory within your app directory (i.e. your appPath).

By default, all files in your app directory are included in your upload to your server, except for node_modules and .git. Dependencies are installed on our build servers (see How are dependencies and native modules handled? above). Also, your devDependencies are excluded from your final app binaries to keep the file size down.

You can also explicitly exclude some files; for example: "appFiles": ["**/*", "!static/**"].

The following are always included if they exist:

• /package.json
• /package-lock.json
• /yarn.lock

Check out the documentation to learn more about appFiles.

# What if I want to trigger a release using a CI platform or a non-interactive script?

You may want to automate builds with your Continuous Integration (CI) provider. To achieve this, simply set the TODESKTOP_ACCESS_TOKEN and TODESKTOP_EMAIL environment variables.

If you want to build-and-release in one step, you can run:

        todesktop build && todesktop release --latest --force

      

# Can I use my own custom electron builds?

Yes, check out the electronMirror config option.

# Can I configure my own certificates?

Yes, this can be done via the web UI ( app.todesktop.com).

# Can I set environment variables for my builds?

Yes, this can be done in the following steps via the web UI ( app.todesktop.com):

1. Click in to your desired application from the applications overview.
2. Navigate to the Settings menu.
3. Navigate to the Build and Deploy submenu.
4. Scroll down and add your environment variable KEY and VALUE.

# Can I auto-update existing users to a ToDesktop release?

Yes, that's no problem. Assuming you have set everything up, this is how it goes:

1. Make a release via ToDesktop that you're happy with.

   1. Both the legacy app and the ToDesktop app need to be signed with a code signing certificate that belongs to the same organisation or individual.
   2. Make sure that this release has the same appId as your legacy app. You can set the appId property in todesktop.json. You can find out the app ID (or bundle identifier) of your legacy app by running the following command in terminal.

           mdls -name kMDItemCFBundleIdentifier -r /Applications/APP_NAME.app
   
         

2. Make a release via your legacy infrastructure, which uses @todesktop/runtime and contains todesktop-runtime-config.json and app-update.yml in the resources directory. The app version must be less than that of step #1.

   1. The content of the todesktop-runtime-config.json file should be:

        {"id":"YOUR_TODESKTOP_ID","wasBuiltByUs":false}

      

b. You should copy the app-update.yml file from the resources directory in your new ToDesktop release. It will look something like this:

        channel: latest
provider: generic
url: https://download.todesktop.com/YOUR_TODESKTOP_ID
updaterCacheDirName: APP_NAME-updater

      

That's it.

Contact us if you're doing this. We'll help you through the process and double check each step.

# But what about X framework or tool?

Here are our other guides:

• How to migrate from electron-builder to ToDesktop.
• How to integrate ToDesktop into an electron-webpack project.
• How to migrate from electron-forge to ToDesktop.
• How to migrate from electron-packager to ToDesktop.

If you need any help, don't hesitate to contact us.

# More features

This is just the tip of the iceberg as far as features go. Check out the @todesktop/cli documentation, the @todesktop/runtime documentation, and app.todesktop.com for more.