Electron Easy Builder

中文文档 | English

This is a packaging tool for Electron applications. When used together with electron-easy-updater, it simplifies implementing both full updates and minimal updates for Electron applications on Windows and macOS.

Why Reinvent the Wheel?

The motivation for this comes from the limitations of the official electron-builder auto-update, which only supports full updates on macOS. It doesn't allow for updating specific files, causing each auto-update to be unnecessarily large. Additionally, the Squirrel auto-update used by Electron requires the update package to be fully signed on macOS.

While using the official electron-builder, I encountered the following issues:

• The Squirrel auto-update on macOS only supports full updates, and the update package must be signed.
• The local testing process for auto-updates is not intuitive and involves complicated steps.
• Too many configuration options, leading to a high learning curve.
• Documentation is lacking; for example, the process for adding a user agreement to a .dmg installer did not work as described in the docs and required reading the source code to complete.
• During .dmg packaging, it’s not possible to verify and notarize signed app files. Manual intervention is needed to manually package the notarized and signed app into a .dmg.
• Electron Forge enforces rigid structure and Webpack limitations, offering no flexibility.

As a result, I decided to write my own packaging tool and update plugin.

Feature Overview

• Packaging for both Windows and macOS platforms.

• Automated full updates and minimal updates for both platforms.

• Multi-language support for installer packages and installation licenses.

  Comparison with electron-builder

  | electron-easy-builder (this) | electron-builder | |----------|----------| | Supports delta updates on macOS without the need for signed update packages | Only supports full updates on macOS, and the update package must be signed | | Local testing is easy | Requires a dev-app-update.yml configuration file for local testing | | Simple functionality with bundled full template example | Documentation is unclear, and some features are not easy to use | | Automated packaging process that handles signing, notarizing, and stapling the .app into a .dmg after app stapling | On macOS, the signing, notarization, and stapling process requires splitting the original packaging flow and using additional tools for notarization and stapling | | Uses Inno Setup for Windows packaging, providing a simpler and more user-friendly installation and update interface, but requires packaging on Windows | Uses NSIS for Windows packaging, which has a steeper learning curve, higher maintenance cost, and requires additional plugins for customizations. However, NSIS can be used to cross-compile an .exe installer package on macOS |

Implementation Principles

The core functionality of this tool still primarily relies on electron-builder (though for Windows packaging, it uses InnoSetup instead of the built-in NSIS in electron-builder). The entire functionality of electron-builder has been broken down, and the required configurations for each module are dynamically generated based on the content of the easy-builder.yml configuration file. These configurations are then applied via API calls to electron-builder.

The goal is to simplify the configuration required for electron-builder packaging. Additionally, the different functionality modules are separated and controlled individually to achieve the features supported by this packaging tool.

How to Use

Installation

npm install electron-easy-builder@latest

Configuration File

You can refer to the full configuration file in lib/easy-builder.template.yml.

Details about the configuration file:

• easy-builder.yml - Overview of the configuration
  • fileAssociations - File associations for the application
  • mac - Configuration for macOS platform
    • sign - Signing configuration
    • notarize - Notarization and stapling configuration
    • pack - Packaging configuration
  • win - Configuration for Windows platform
    • sign - Signing configuration
    • pack - Packaging configuration

Command-Line Options

The specific commands are as follows:

• Options:
  • easy-builder -V - View the current command-line tool version.
  • easy-builder -h - View command help.
• Commands:

  • easy-builder init [options] <string> - Initialize the configuration file. This command will create an easy-builder.yml template file in the current working directory.

    Optional Parameters :

    • -d, --dir <path> - Specify the project directory. By default, the configuration file will be created in the current working directory. Use this option to create the configuration file in a specified path.

  • easy-builder build [options] <string> - Build the application.

    Optional Parameters:

    • -d, --dir <path> - Specify the project directory. The protocol files in this path will be compiled. If not specified, the current directory will be used by default.
    • -m - Compile the application for macOS platform.
    • -w - Compile the application for Windows platform.
    • easy-builder help [command] - View help for a specific command. Use this to get detailed information on commands like init, build, etc.

Others

• The current version of electron-builder being used is 24.6.3. The latest version may cause issues where the tool can only run with administrator privileges due to https://github.com/electron-userland/electron-builder/issues/8149.
• On Windows, if you encounter the error "Unable to commit changes`, please refer to https://github.com/electron/packager/issues/590#issuecomment-1416237580 to disable your antivirus software and try again. This issue occurs because the antivirus software has protected the newly generated files and prevents other processes from modifying them.

TODO

• Generation of .icns and .ico icon files.
• Support for the minimum required operating systems.

Acknowledgments

A big thank you to electron-builder, a comprehensive packaging tool that supports API calls.