Migrate from electron-builder to ToDesktop

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

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

# Migrating from electron-builder's CLI

You might have npm scripts like the following in your package.json:

        ...
"scripts": {
  "pack": "electron-builder --dir",
  "dist": "electron-builder",
  "postinstall": "electron-builder install-app-deps"
}
...

      

# Distributing a release

Instead of running electron-builder like above, you'd run todesktop build && todesktop release --latest --force. You will only need to run this on one machine, we'll compile your app for Linux, Mac, and Windows.

• todesktop build takes care of the compilation, code-signing, notarization, native installers, and more.

• todesktop release publishes this build as a new release, i.e. new downloads and an auto-update for existing users. If ran without any arguments/flags it will present a list of builds to choose from. --latest selects the latest build, and --force bypasses a confirmation prompt.

Once complete, you'll be presented with the download links for your release.

# Packing into a local binary

Instead of running electron-builder --dir like above, you'd run todesktop build.

This is handy for testing a build before release. You can release it then via todesktop release or our web UI at app.todesktop.com. It only takes a few seconds.

If you just want a quick build for local testing, you can run todesktop build --code-sign=false which will disable code-signing and notarization.

You can always keep electron-builder for testing packed applications locally but make sure your electron-builder and ToDesktop config are aligned. You don't want any surprises when you go to production.

# What should I do instead of electron-builder install-app-deps?

We automatically rebuild your dependencies and native modules for the Node.js version your Electron app is using. However, if you're using electron-builder install-app-deps to ensure dependencies are rebuilt correctly in development, you can replace it with electron-rebuild. Also see How are dependencies and native modules handled?

# Putting it all together

Your updated package.json now should look something like:

        ...
"scripts": {
  "pack": "todesktop build",
  "dist": "todesktop build && todesktop release --latest --force",
  "postinstall": "electron-rebuild"
}
...

      

I would also rename those script names (e.g. release instead of dist) but I'll leave that up to you.

# Migrating from electron-builder's programmatic API

Let's say you have a build.js file which calls electron-builder programmatically. The story is similar.

If you're creating a local packed application, replace that with a call to todesktop build. If you're distributing a release, replace that with a call to todesktop release.

If you want to keep your build.js file, you can programmatically call our CLI commands. Otherwise, you could add npm scripts in your package.json as we showed above.

If you're wondering where your configuration goes, see Migrating your configuration below.

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

The first notable difference from electron-builder's configuration is that ToDesktop doesn't make any assumptions. For example, electron-builder will automatically look in certain directories (e.g. resources) for certain files and use them if they exist. ToDesktop is explicit. If you want to use a custom entitlements file, you must set mac.entitlements .

# Extra resources

Another notable difference is the extraResources option. This is used to add additional files into the resources directory of your app binaries.

With electron-builder, this can be used in a many forms, e.g. FileSet. Some support globs, some support relative files, etc. We have a single input format for this, which looks something like:

        [
  { "from": "./static/image.png" },
  { "from": "./static/anotherImage.png", "to": "images" },
  { "from": "./static", "to": "assets" }
]

      

It works mostly like electron-builder's FileSet. If you're using this option, please read the documentation. It's not difficult to understand, it's just that it might work slightly different to what you're used to.

# But how do I set X?

If there are any options missing which you need, let us know. We can roll these kind of options out quickly.

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