Migrate from electron-forge to ToDesktop

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

# Learn the basics

Typically, replacing electron-forge 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-forge specifics.

Let's assume your package.json's scripts look like the following:

        ...
"scripts": {
  "start": "electron-forge start",
  "package": "electron-forge package",
  "make": "electron-forge make",
  "publish": "electron-forge publish"
},
...

      

We're going to replace your make, package, and publish commands with ToDesktop.

# Removing electron-forge

You might wonder what's left that electron-forge gives you. That would be the start command. This launches your application and has some CLI flags which enable a logger, inspector, etc.

If you don't use these, you could remove electron-forge entirely and change the start command to call electron .. This will launch your app with the official Electron CLI.

If you want to keep electron-forge for the start command or another reason / feature, just keep in mind that any electron-forge configuration is ignored by ToDesktop.

From here on, I'm going to assume we're removing electron-forge entirely. To do this, remove all dependencies that contain electron-forge in the name (and electron-squirrel-startup too if you have it). Run one of the following:

        yarn remove electron-squirrel-startup @electron-forge/cli @electron-forge/maker-deb @electron-forge/maker-rpm @electron-forge/maker-squirrel @electron-forge/maker-zip @electron-forge/plugin-auto-unpack-natives @electron-forge/plugin-fuses

npm uninstall electron-squirrel-startup @electron-forge/cli @electron-forge/maker-deb @electron-forge/maker-rpm @electron-forge/maker-squirrel @electron-forge/maker-zip @electron-forge/plugin-auto-unpack-natives @electron-forge/plugin-fuses

      

# New package.json scripts

        // yarn version
"scripts": {
  "start": "electron .",
  "build": "yarn && todesktop build",
  "quick-build": "yarn && todesktop build . --code-sign=false",
  "release": "yarn && todesktop build && todesktop release --latest --force"
},
// npm version
"scripts": {
  "start": "electron .",
  "build": "npm install && todesktop build",
  "quick-build": "npm install && todesktop build . --code-sign=false",
  "release": "npm install && todesktop build && todesktop release --latest --force"
},

      

The release script releases your app. Specifically, it first runs yarn just to be safe, then it will run todesktop build && todesktop release --latest --force. This last command uploads your app to our servers and kicks off Linux, Mac, and Windows builds. It'll then release new downloads and an auto-update. Overall, this is like your old publish command.

The build script is just like the above, except it won't release new downloads or an auto-update. This is helpful for testing before rolling out a release. After you do your testing, you can optionally go to app.todesktop.com and click a button to release this build (it only takes a few seconds). The contents of the script is the same, except todesktop build is the final step. Overall, this is like your old make command.

In our opinion, the ideal release process is to run build , download and test the app, then use todesktop release / our web UI to release that build.

For quicker development builds you can use the quick-build script, 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. Overall, this is somewhat like your old package command.

# 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-forge configuration you have, whether that's a property in your package.json, a config file, or any config you pass to electron-forge programmatically. That's a minimal example above. Check out the documentation for the full list.

If you are passing config to makers, setting packagerConfig, or anything like that, 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-packager to ToDesktop.

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