packaging

107 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

Electron Forge recommended for packaging and distribution

Electron Forge is the recommended tool for packaging and distributing Electron apps. It handles both packaging and distribution tasks. The documentation for Electron Forge is available at electronforge.io, and there is a Packaging and Distribution tutorial available as part of the Electron tutorial.

Manual packaging with prebuilt binaries directory structure

To manually distribute an Electron app using prebuilt binaries, download Electron's prebuilt binaries from https://github.com/electron/electron/releases. Create a folder named 'app' containing package.json, main.js, and index.html, then place it in Electron's resources directory. On macOS, the path is electron/Electron.app/Contents/Resources/app/. On Windows and Linux, the path is electron/resources/app/. Execute Electron.app on macOS, electron on Linux, or electron.exe on Windows to run the app.

Using asar archives for app distribution

Instead of shipping app source files directly, package the app into an asar archive to improve file reading performance on Windows if not already using a bundler like Parcel or Webpack. Rename the archive to app.asar and place it in Electron's resources directory. On macOS, the path is electron/Electron.app/Contents/Resources/app.asar. On Windows, the path is electron/resources/app.asar. Electron will automatically try to read from the archive on startup. More details are available in the electron/asar repository.

Rebranding Electron app on Windows

On Windows, rename electron.exe to any desired name and edit its icon and other information using tools like rcedit.

Rebranding Electron app on Linux

On Linux, rename the electron executable to any desired name.

Rebranding Electron app on macOS

On macOS, rename Electron.app to the desired app name. Then rename the following fields in Electron.app/Contents/Info.plist and Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist: CFBundleDisplayName, CFBundleIdentifier, and CFBundleName. Optionally rename the helper app executable to avoid showing 'Electron Helper' in Activity Monitor, ensuring the helper app's executable file name is also updated. The resulting structure should be MyApp.app/Contents/Info.plist, MyApp.app/Contents/MacOS/MyApp, and MyApp.app/Contents/Frameworks/MyApp Helper.app/Contents/MacOS/MyApp Helper.

Alternative macOS rebranding by building from source

Electron can also be rebranded by changing the product name and building from source. Set the build argument electron_product_name = 'YourProductName' in the args.gn file and rebuild. This approach is not recommended because setting up the environment to compile from source is not trivial and takes significant time.

ASAR archive purpose and benefits

ASAR is a simple extensive archive format designed for Electron apps. By bundling the app into an ASAR archive, you can mitigate issues around long path names on Windows, speed up `require`, and conceal source code from cursory inspection.

ASAR virtual file system behavior

The bundled app runs in a virtual file system where most APIs work normally. Node APIs like `fs.readFile` and `require` treat ASAR archives as virtual directories, and files within them as normal files in the filesystem.

Reading files from ASAR archive with Node API

Files in an ASAR archive can be read using standard Node.js `fs` APIs by treating the archive path as a directory path. For example, `fs.readFileSync('/path/to/example.asar/file.txt')` reads a file from within the archive.

Loading modules from ASAR archive

Modules can be loaded directly from an ASAR archive using `require` with the archive path included in the module path. For example, `require('./path/to/example.asar/dir/module.js')` loads a module from within the archive.

Loading web pages from ASAR archive with BrowserWindow

Web pages stored in an ASAR archive can be loaded using BrowserWindow's `loadURL` method with a `file://` protocol URL pointing to the HTML file within the archive. For example, `win.loadURL('file:///path/to/example.asar/static/index.html')`.

Web API access to ASAR archive files

Files in an ASAR archive can be requested from web pages using the `file:` protocol. ASAR archives are treated as directories by the web API, allowing access to archive contents like `file:///path/to/example.asar/file.txt`.

original-fs module for raw ASAR file access

The built-in `original-fs` module provides original `fs` APIs without ASAR support, allowing you to read an ASAR archive as a raw file. This is useful for operations like verifying the archive's checksum. Use `const originalFs = require('original-fs')` and call `originalFs.readFileSync('/path/to/example.asar')`.

process.noAsar flag to disable ASAR support

Setting `process.noAsar = true` disables ASAR support in the `fs` module, allowing the module to read ASAR archives as normal files instead of treating them as virtual directories.

ASAR archives are read-only

ASAR archives cannot be modified. All Node APIs that modify files will not work with ASAR archives.

Cannot set working directory inside ASAR archive

You cannot set the working directory to directories within ASAR archives because no actual directories exist in the filesystem. Passing ASAR archive paths as the `cwd` option to APIs will cause errors.

APIs requiring extra unpacking from ASAR archives

Some APIs that rely on passing the real file path to underlying system calls will trigger automatic extraction of files from ASAR archives to temporary files. These APIs are: `child_process.execFile`, `child_process.execFileSync`, `fs.open`, `fs.openSync`, and `process.dlopen` (used by `require` on native modules). This adds overhead compared to APIs that can read directly from archives.

fs.stat returns guessed information for ASAR archive files

The `Stats` object returned by `fs.stat` and related functions for files in ASAR archives is generated by guessing, because these files do not exist on the filesystem. The `Stats` object should only be trusted for getting file size and checking file type, not other properties.

Only execFile supported for executing binaries in ASAR archive

Only `child_process.execFile` is supported for executing binaries inside an ASAR archive. `child_process.exec` and `child_process.spawn` are not supported because they accept `command` instead of `file` as input, and there is no reliable way to determine whether a command uses a file in the archive or to replace the path without side effects.

Using --unpack option to exclude files from ASAR archive

Files can be excluded from an ASAR archive using the `--unpack` option when packing. For example, `asar pack app app.asar --unpack *.node` creates an `app.asar` file with an accompanying `app.asar.unpacked` folder containing the unpacked files. This is useful for native modules and files accessed by APIs that require unpacking, and helps avoid triggering anti-virus scanners.

Electron development is unopinionated

Electron development has no single prescribed way to develop, build, package, or release applications. Additional features for both build-time and runtime can be found on npm as individual packages, allowing developers to build the app and build pipeline they need.

Boilerplate vs CLI tool differences

A boilerplate is a starting point or template repository that can be cloned and customized. A command line tool continues to support the developer throughout the development and release cycle, is more helpful and supportive, but enforces guidelines on code structure and build practices. For beginners, using a command line tool is likely to be more helpful.

Electron Forge overview

Electron Forge is a tool for packaging and publishing Electron applications that unifies Electron's tooling ecosystem into a single extensible interface. It comes with a ready-to-use Webpack template, includes example TypeScript configuration and two customizable configuration files. Forge uses the same core modules as the greater Electron community, such as @electron/packager, so changes made by Electron maintainers benefit Forge users.

electron-builder overview

electron-builder is described as a complete solution to package and build a ready-for-distribution Electron app, focusing on an integrated experience. It adds a single dependency focused on simplicity and manages all further requirements internally. electron-builder replaces features and modules used by Electron maintainers, such as the auto-updater, with custom ones that are generally tighter integrated but have less in common with popular Electron apps like Atom, Visual Studio Code, or Slack.

electron-react-boilerplate overview

electron-react-boilerplate is a solid boilerplate for developers who want only a template without additional tools. It is quite popular in the community and uses electron-builder internally.

Electron Packager and Forge darwinDarkModeSupport option

Both Electron Packager and Electron Forge have a darwinDarkModeSupport option that automates Info.plist changes during app build time to support dark mode on macOS.

Distribution workflow: four main steps

To distribute an Electron app to users, follow these four steps: (1) Package all resources and assets into an executable and rebrand it; (2) Code sign the application; (3) Publish by uploading installers online or to platform app stores; (4) Implement auto-updating so users receive updates without manually downloading new versions.

Packaging options: Electron Forge or manual

To package an Electron app, you can either use specialized tooling like Electron Forge or do it manually. Packaging involves bundling all resources and assets into an executable and rebranding it.

Distribution platforms require additional build steps

Uploading your app to platform app stores (Mac App Store, Windows Store, or Snapcraft for Linux) requires another build step in addition to the direct download distribution method.

Auto-updater enables updates without manual downloads

Electron's auto-updater feature allows you to deliver application updates to users without forcing them to manually download new versions of your application.

Electron Forge main workflows

Electron Forge handles three main steps in app distribution: packaging your application, generating executables and installers for each OS (make), and publishing these files to online platforms for download (publish).

electron-builder alternative to Forge

electron-builder is a third-party community-maintained tool described as a complete solution to package and build a ready-for-distribution Electron app. It adds a single dependency and manages all further requirements internally. It replaces features used by Electron maintainers, such as the auto-updater, with custom implementations.

Hydraulic Conveyor alternative to Forge

Hydraulic Conveyor is a commercial desktop app deployment tool (free for open source projects) that supports cross-building and signing of all packages from any OS without multi-platform CI. It performs synchronous web-style updates on each app start, requires no code changes, uses plain HTTP servers for updates, and replaces Electron auto-updaters with Sparkle on macOS, MSIX on Windows, and Linux package repositories.

Getting started with Electron Forge

For beginners, follow Electron's tutorial to develop, build, package and publish the first Electron app. Developers with an existing app on their machine can start at step 5 of the tutorial, which covers packaging and distribution.

Electron Forge purpose and scope

Electron Forge is a tool for packaging and publishing Electron applications. It unifies Electron's build tooling ecosystem into a single extensible interface to make it easier to create and distribute Electron apps.

Electron Forge fuses plugin

If using Electron Forge to distribute your application, you can flip fuses using @electron-forge/plugin-fuses, which comes pre-installed with all templates.

Force remote checksums for custom Electron mirrors

If your mirror serves artifacts with different checksums than the official Electron release, set `electron_use_remote_checksums=1` directly or configure it in a `.npmrc` file to force Electron to use the remote `SHASUMS256.txt` file for checksum verification instead of embedded checksums.

Electron binary cache locations by platform

The @electron/get module caches downloaded binaries locally to avoid stressing the network. Default cache locations are: Linux: `$XDG_CACHE_HOME` or `~/.cache/electron/`, macOS: `~/Library/Caches/electron/`, Windows: `$LOCALAPPDATA/electron/Cache` or `~/AppData/Local/electron/Cache/`. Older Electron versions may also cache in `~/.electron`. Override the location using the `electron_config_cache` environment variable.

Electron cache structure and format

The cache contains the version's official zip file and a checksum, stored as `[checksum]/[filename]`. For example, a typical cache entry looks like: `a91b089b5dc5b1279966511344b805ec84869b6cd60af44f800b363bba25b915/electron-v15.3.1-darwin-x64.zip`.

Troubleshoot Electron npm install network errors

When `npm install electron` fails with errors like `ELIFECYCLE`, `EAI_AGAIN`, `ECONNRESET`, or `ETIMEDOUT`, these indicate network problems, not issues with the electron package. Solutions include switching networks, waiting and retrying, or downloading Electron directly from the releases page.

Fix Electron npm install EACCESS permission errors

If Electron installation fails with an `EACCESS` error, you may need to fix npm permissions. If the error persists, try setting the `unsafe-perm` flag to true: `sudo npm install electron --unsafe-perm=true`.

Show Electron download progress with --verbose flag

On slower networks, use the `--verbose` flag to show download progress during Electron installation: `npm install --verbose electron`.

Force re-download of Electron binary and SHASUM

To force a re-download of the Electron asset and the SHASUM file, set the `force_no_cache` environment variable to `true`.

Install Electron as development dependency

The preferred method to install Electron is using npm as a development dependency by running `npm install electron --save-dev`. This installs prebuilt Electron binaries.

Electron binary downloads automatically on first run

The Electron binary is downloaded by default the first time you run Electron in development mode (for example, `electron .`). The binary is crucial to the function of any Electron app as it contains the native implementations that the JavaScript API binds to.

Install Electron binary on demand with install-electron script

To install the Electron binary on demand instead of automatically, run the `install-electron` bin script included in the `electron` package using `npx install-electron --no`.

Run Electron ad-hoc without npm install

You can run Electron without installing it to your project using `npx electron .`. This runs the current working directory with Electron, but note that any dependencies in your app will not be installed.

Override Electron download architecture with ELECTRON_INSTALL_ARCH

Set the `ELECTRON_INSTALL_ARCH` environment variable to change the architecture downloaded (for example, `x64` on an `arm64` machine). Example: `ELECTRON_INSTALL_ARCH=x64 electron .`. Supported architectures are: x64 (Intel Mac and 64-bit Windows), arm64 (Apple silicon, Windows on ARM, ARM64 Linux).

Override Electron download platform with ELECTRON_INSTALL_PLATFORM

Set the `ELECTRON_INSTALL_PLATFORM` environment variable to specify the platform using the `--platform` flag (for example, `win32`, `linux`, `darwin`, `mas`). Example: `ELECTRON_INSTALL_PLATFORM=mas electron .`. Supported platforms are: darwin, mas (Mac App Store), win32, linux.

Configure HTTP proxy for Electron downloads

To use an HTTP proxy for Electron binary downloads, set the `ELECTRON_GET_USE_PROXY` environment variable to any value, plus additional environment variables depending on your host system's Node version. Refer to Node 10+ proxy environment variables or earlier Node versions as needed.

Custom Electron mirror URL construction

The @electron/get module downloads Electron binaries using a URL composed as: `url = ELECTRON_MIRROR + ELECTRON_CUSTOM_DIR + '/' + ELECTRON_CUSTOM_FILENAME`. By default, `ELECTRON_CUSTOM_DIR` is set to `v$VERSION`. Use the `{{ version }}` placeholder to customize the directory format (for example, `version-{{ version }}` resolves to `version-5.0.0`, `{{ version }}` resolves to `5.0.0`).

Use China CDN mirror for Electron downloads

To use the China CDN mirror for Electron downloads, set `ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"`.

Deep links only work in packaged apps on macOS and Linux

Protocol handler support for deep links only functions when the app is packaged. It does not work when launching from the command-line during development on macOS and Linux. Windows behavior may differ.

macOS requires Info.plist update for protocol handler

When packaging an Electron app for macOS with deep link support, the Info.plist file must be updated to include the protocol handler configuration for the app to register correctly as a handler for the custom protocol.

Linux requires .desktop file update for protocol handler

When packaging an Electron app for Linux with deep link support, the .desktop file for the app must be updated to include the protocol handler configuration. Some Electron bundling tools handle this automatically.

Electron Forge protocol configuration for macOS

In Electron Forge's packagerConfig, add a 'protocols' array with objects containing 'name' and 'schemes' fields. Example: { "protocols": [ { "name": "Electron Fiddle", "schemes": ["electron-fiddle"] } ] }

Electron Forge protocol configuration for Linux

In Electron Forge's makers configuration for the deb maker, add 'mimeType' array to specify the protocol handlers. Example: { "name": "@electron-forge/maker-deb", "config": { "mimeType": ["x-scheme-handler/electron-fiddle"] } }

Electron Packager API protocol configuration

When using Electron Packager's API, pass a 'protocols' array in the packager options containing objects with 'name' and 'schemes' fields: { protocols: [ { name: 'Electron Fiddle', schemes: ['electron-fiddle'] } ] }

Electron Packager CLI protocol flags

Use the electron-packager CLI with --protocol=<protocol-name> and --protocol-name="<display-name>" flags to configure protocol handling. Example: npx electron-packager . --protocol=electron-fiddle --protocol-name="Electron Fiddle"

Give your agent this brain