Migrate from electron-packager to ToDesktop

This is a guide for those looking to integrate ToDesktop CLI into an existing Electron project, replacing electron-packager.

# Learn the basics

Typically, replacing electron-builder with ToDesktop means mostly deleting code. However, first, have a skim through our generic Electron guide: How to integrate ToDesktop into your Electron application.

Welcome back, let's look at some electron-packager specifics. ToDesktop not only replaces the packaging of your binaries, but also the infrastructure, like servers for auto-updates, downloads, CDN, etc.

Previously, you might have ran electron-packager commands on multiple machines and had a process for uploading and rolling out a new version. This will be replaced by one ToDesktop command you run from just one machine.

# Removing electron-packager

First, remove all electron-packager dependencies and usage. Technically, you don't have to do this, but it's strongly encouraged. If you are keeping it for a specific reason:

1. Let us know and we'll factor that into ToDesktop.
2. Keep in mind that your electron-packager configuration will be ignored by ToDesktop.

From here on, I'm going to assume we're removely electron-packager entirely.

# New CLI commands

We recommend calling our CLI commands from npm scripts in your package.json but I'll leave that up to you. The two commands you need to learn are:

• todesktop build which uploads your app to our servers to kick off Linux, Mac, and Windows build. It takes care of the compilation, code-signing, native installers, and so on. It does not release the build to your users though. This is helpful for testing before rolling out a release.
• todesktop release which releases a build (it only takes a few seconds). It publishes new downloads and an auto-update. Alternatively, you can click a button in our web UI at app.todesktop.com.

For quicker development builds you can run todesktop build --code-sign=false, which disables code-signing and notarization. The only downside is that you lose the option to release this build to production. You'll need to trigger a new one.

# How can I control which platforms to build for?

If you want to change which operating systems you build for or which installers are created, you can control this in your app settings in the web UI at app.todesktop.com. We support a long list of options, and even some hidden ones. If you need a platform that isn't there, just let us know and we'll add it quickly for you.

As for platform-specific options, e.g. using a different icon for your Windows app, these are set in your todesktop.json. What's this todesktop.json? Read on.

# Migrating your configuration

As is covered in our generic Electron guide, you'll need to create a todesktop.json which contains configuration for ToDesktop.

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

      

This replaces any electron-packager configuration you have, whether that's options you pass to the electron-packager CLI or programmatic API. That's a minimal example above. Check out the documentation for the full list.

Please review our options thoroughly so everything is covered. If you're unsure about anything, let us know, and we'll jump on it.

# Other common questions

• How are dependencies and native modules handled?
• What if I need to compile my app code?
• What if my app is in a sub-directory?"
• How can I exclude unnecessary files?
• What if I want to trigger a release using a CI platform or a non-interactive script?
• Can I use my own custom electron builds?
• Can I configure my own certificates?
• Can I set environment variables for my builds?
• Can I auto-update existing users to a ToDesktop release?

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

# Other migration guides

• How to integrate ToDesktop into your Electron application.
• 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.

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