Electron Builder

https://www.electron.build/
Admin
A complete solution to package and build ready for distribution Electron apps for macOS, Windows and...
Tokens:58,849
Snippets:951
Trust Score:9.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### FPM Options Example

Source: https://www.electron.build/docs/linux

Example of passing advanced FPM options for installation scripts.

```json
["--before-install=build/deb-preinstall.sh", "--after-upgrade=build/deb-postinstall.sh"]
```

--------------------------------

### Snapcraft configuration example

Source: https://www.electron.build/docs/api/electron-builder.Interface.WindowsSignTaskConfiguration

Example configuration for Snapcraft using the core24 base.

```json
{ "snapcraft": { "base": "core24", "core24": { "useLXD": true } } }
```

--------------------------------

### Example macOS Kernel Extension Installation Script

Source: https://www.electron.build/docs/tutorials/macos-kernel-extensions

This shell script demonstrates unloading old kernel extensions, removing them, and then installing and loading new ones. Ensure the script is executable and starts with `#!/bin/sh`.

```shell
#!/bin/sh

echo "Unloading and uninstalling old extensions..."
# unload old extensions
sudo kextunload /Library/Extensions/myExt.kext

# delete old extensions
sudo rm -rf /Library/Extensions/myExtension.kext

# install new extensions
echo "Installing and loading new extensions..."
sudo cp -R myExt.kext /Library/Extensions/myExt.kext
sudo kextload /Library/Extensions/myExt.kext/
```

--------------------------------

### Configure Auto-Install Event

Source: https://www.electron.build/docs/features/auto-update

Sets the update installation timing to occur at the start of the next application launch.

```javascript
autoUpdater.autoInstallEvent = "onNextLaunch"
```

--------------------------------

### Install Flatpak runtimes

Source: https://www.electron.build/docs/troubleshooting

Install the necessary Freedesktop platform and SDK runtimes to prevent Flatpak build failures.

```bash
flatpak install flathub org.freedesktop.Platform//24.08  

flatpak install flathub org.freedesktop.Sdk//24.08
```

--------------------------------

### Initialize Project

Source: https://www.electron.build/docs

Clone the starter repository and install dependencies.

```bash
git clone https://github.com/electron/electron-quick-start

cd electron-quick-start

npm install

npm install electron-builder --save-dev
```

--------------------------------

### Common Build Commands

Source: https://www.electron.build/docs/cli

Examples of building for multiple platforms or specific formats.

```bash
electron-builder -mwl
```

```bash
electron-builder --linux deb tar.xz
```

```bash
electron-builder --windows nsis:ia32
```

--------------------------------

### Install snapcraft and multipass on Linux

Source: https://www.electron.build/docs/features/multi-platform-build

Installs snapcraft and multipass, required for building snap packages on Linux.

```shell
sudo snap install snapcraft --classic
sudo snap install multipass --beta --classic
```

--------------------------------

### Configure PKCS#11 Signing Mode

Source: https://www.electron.build/docs/migration/v27-breaking-changes

Example configuration for the beta PKCS#11 signing mode.

```json
{

  "win": {  

    "sign": {  

      "type": "pkcs11",  

      "pkcs11Module": "/usr/lib/x86_64-linux-gnu/opensc-pkcs11.so",  

      "pkcs11KeyUri": "pkcs11:token=MyToken;object=MyKey;type=private",  

      "certificateFile": "cert.pem"  

    }  

  },  

  "toolsets": { "winCodeSign": "1.3.0" }  

}
```

--------------------------------

### Linux Icon File Structure Example

Source: https://www.electron.build/docs/features/icons-and-images

Example of the expected file structure for Linux icon assets. Files must be named according to their pixel dimensions (e.g., 16x16.png).

```bash
build/icons/
├── 16x16.png
├── 32x32.png
├── 48x48.png
├── 128x128.png
├── 256x256.png
└── 512x512.png
```

--------------------------------

### Install Linux build dependencies

Source: https://www.electron.build/docs/features/multi-platform-build

Installs necessary tools for building on Linux, specifically libopenjp2-tools for distributable formats.

```shell
sudo apt-get install --no-install-recommends -y libopenjp2-tools
```

--------------------------------

### Configure releaseInfo via command line

Source: https://www.electron.build/docs/mac

Example of setting release notes using the command line interface.

```bash
-c.releaseInfo.releaseNotes="new features"
```

--------------------------------

### Install electron-builder

Source: https://www.electron.build/docs

Add electron-builder as a development dependency to your project.

```bash
yarn add electron-builder --dev
```

--------------------------------

### Build Linux ARM on x64 via Docker

Source: https://www.electron.build/docs/architecture

Setup QEMU emulation and build an ARM64 AppImage on an x64 host.

```bash
# Install QEMU support (one-time setup)

docker run --privileged --rm tonistiigi/binfmt --install arm64,arm


# Build ARM64 AppImage

docker run --rm \

  -v ${PWD}:/project \

  -v ~/.cache/electron:/root/.cache/electron \

  -v ~/.cache/electron-builder:/root/.cache/electron-builder \

  --platform linux/arm64 \

  electronuserland/builder \

  /bin/bash -c "npm ci && npx electron-builder --linux --arm64"
```

--------------------------------

### Configure R2 Publishing

Source: https://www.electron.build/docs/publish

Example configuration for the build object to use R2 as the publishing provider.

```json
{

  "build": {

    "publish": {

      "provider": "r2",

      "bucket": "my-releases",

      "accountId": "abcdef1234567890abcdef1234567890",

      "publicUrl": "https://pub-abcdef1234567890abcdef1234567890.r2.dev"

    }

  }

}
```

--------------------------------

### beforeBuild Hook

Source: https://www.electron.build/docs/features/hooks

Executes before native dependencies are installed. Returning false skips the dependency installation.

```javascript
beforeBuild: async (context) => {  

  // context: BeforeBuildContext  

  // { appDir, electronVersion, platform, arch }  

  console.log("Building for:", context.platform.name, context.arch)  

  // return false to skip dependency install  

}  
```

--------------------------------

### Install NSIS Web Installer Maker for Electron Forge

Source: https://www.electron.build/docs/features/electron-forge

Install the NSIS web installer maker package as a development dependency.

```bash
npm install --save-dev electron-forge-maker-nsis-web
```

--------------------------------

### Electron Builder CLI Help Output

Source: https://www.electron.build/docs/cli

Displays the full list of commands, building options, publishing settings, and usage examples for the electron-builder CLI.

```bash
electron-builder  

  

Build  

  

Commands:  

  electron-builder build                    Build                                [default]  

  electron-builder install-app-deps         Install app deps  

  electron-builder node-gyp-rebuild         Rebuild own native code  

  electron-builder publish                  Publish a list of artifacts  

  electron-builder create-self-signed-cert  Create self-signed code signing cert for Windo  

                                  ws apps  

  electron-builder start                    Run application in a development mode using el  

                                  ectron-webpack  

  electron-builder clear-cache              Clear the electron-builder default cache direc  

                                  tory  

  electron-builder migrate-schema           Migrate build config from v26 to v27 format  

  

Building:  

  -m, -o, --mac, --macos       Build for macOS, accepts target list (see https:/  

                               /www.electron.build/mac).                 [array]  

  -l, --linux                  Build for Linux, accepts target list (see https:/  

                               /www.electron.build/linux)                [array]  

  -w, --win, --windows         Build for Windows, accepts target list (see https  

                               ://www.electron.build/win)                [array]  

      --x64                    Build for x64                           [boolean]  

      --ia32                   Build for ia32                          [boolean]  

      --armv7l                 Build for armv7l                        [boolean]  

      --arm64                  Build for arm64                         [boolean]  

      --universal              Build for universal                     [boolean]  

      --dir                    Build unpacked dir. Useful to test.     [boolean]  

      --prepackaged, --pd      The path to prepackaged app (to pack in a distrib  

                               utable format)  

      --projectDir, --project  The path to project directory. Defaults to curren  

                               t working directory.  

  -c, --config                 The path to an electron-builder config. Defaults  

                               to `electron-builder.yml` (or `json`, or `json5`,  

                                or `js`, or `ts`), see https://www.electron.buil  

                               d/configuration  

  

Publishing:  

  -p, --publish  Publish artifacts, see https://www.electron.build/publish  

                [choices: "onTag", "onTagOrDraft", "always", "never", undefined]  

  

Other:  

      --help     Show help                                             [boolean]  

      --version  Show version number                                   [boolean]  

  

Examples:  

  electron-builder -mwl                     build for macOS, Windows and Linux  

  electron-builder --linux deb tar.xz       build deb and tar.xz for Linux  

  electron-builder --win --arm64            build for Windows arm64  

  electron-builder -c.extraMetadata.foo=ba  set package.json property `foo` to `  

  r                                         bar`  

  electron-builder --config.nsis.unicode=f  configure unicode options for NSIS  

  alse  

  

See https://electron.build for more documentation.
```

--------------------------------

### Defer Update Installation

Source: https://www.electron.build/docs/features/auto-update

Triggers an update installation with specific silent and restart configurations.

```javascript
autoUpdater.quitAndInstall({ isSilent: true, isForceRunAfter: true, waitUntilNextLaunch: true })
```

--------------------------------

### Setup Node.js and Cache npm Packages

Source: https://www.electron.build/docs/features/github-actions

Configures the Node.js environment for a GitHub Actions workflow and enables caching for npm packages to speed up subsequent builds. Uses the 'actions/setup-node' action.

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm    # caches ~/.npm  
```

--------------------------------

### Install Snap Maker for Electron Forge

Source: https://www.electron.build/docs/features/electron-forge

Install the Snap maker package as a development dependency for your Electron Forge project.

```bash
npm install --save-dev electron-forge-maker-snap
```

--------------------------------

### Install 32-bit build tools on Linux

Source: https://www.electron.build/docs/features/multi-platform-build

Installs GCC and G++ for 32-bit architecture, enabling 32-bit builds from a 64-bit machine on Linux.

```shell
sudo apt-get install --no-install-recommends -y gcc-multilib g++-multilib
```

--------------------------------

### Install bsdtar on Linux

Source: https://www.electron.build/docs/features/multi-platform-build

Installs bsdtar, a utility for creating and extracting archives, required for pacman builds on Linux.

```shell
sudo apt-get install --no-install-recommends -y bsdtar
```

--------------------------------

### Rebuild Native Dependencies

Source: https://www.electron.build/docs/features/build-lifecycle

Fires before native dependency installation or rebuild. Returning `false` skips native dependency installation.

```javascript
beforeBuild: async ({ appDir, electronVersion, platform, arch }) => {
  console.log(`Building native deps for ${platform.name} ${arch}`)
  // return false to skip; useful when node_modules are managed externally
}
```

--------------------------------

### Configure Monorepo Setup

Source: https://www.electron.build/docs/contents

Define a custom app directory when the project root is not the application root.

```yaml
directories:  

  app: packages/app   # app directory is not the project root  

  

files:  

  - "**/*"  

  - "!src/**"  
```

--------------------------------

### Configure S3 Publishing

Source: https://www.electron.build/docs/publish

Example configuration for the S3 provider within the build settings.

```json
{

 "build":

   "publish": {

     "provider": "s3",

     "bucket": "bucket-name"

   }

 }

}
```

--------------------------------

### electron-builder install-app-deps

Source: https://www.electron.build/docs/cli

Installs application dependencies.

```APIDOC
## electron-builder install-app-deps

### Description
Installs the application dependencies required for the build process.
```

--------------------------------

### Multiple Glob Patterns Example

Source: https://www.electron.build/docs/file-patterns

Demonstrates how to use multiple glob patterns to include and exclude files. Use this to define a set of files for your build, excluding specific types or files while including others.

```json
[
  
  // match all files  
  "**/*",  
  
  // except for js files in the foo/ directory  
  "!foo/*.js",  
  
  // unless it's foo/bar.js  
  "foo/bar.js",  
  
]
```

--------------------------------

### Run an AppImage file

Source: https://www.electron.build/docs/appimage

Make the AppImage file executable and run it directly without installation or root privileges.

```bash
chmod +x MyApp-1.0.0-x86_64.AppImage  

./MyApp-1.0.0-x86_64.AppImage  
```

--------------------------------

### Build Windows on Linux/macOS via Docker

Source: https://www.electron.build/docs/architecture

Use the Wine-based Docker image to generate Windows installers on non-Windows hosts.

```bash
docker run --rm \

  -v ${PWD}:/project \

  -v ~/.cache/electron:/root/.cache/electron \

  -v ~/.cache/electron-builder:/root/.cache/electron-builder \

  electronuserland/builder:wine \

  /bin/bash -c "npm ci && npx electron-builder --win"
```

--------------------------------

### JSign Signing Script Example

Source: https://www.electron.build/docs/tutorials/code-signing-windows-apps-on-unix

A JavaScript file to execute JSign for code signing. It reads certificate name and token password from environment variables and constructs the command-line arguments for JSign.

```javascript
exports.default = async function(configuration) {
  // do not include passwords or other sensitive data in the file
  // rather create environment variables with sensitive data
  const CERTIFICATE_NAME = process.env.WINDOWS_SIGN_CERTIFICATE_NAME;
  const TOKEN_PASSWORD = process.env.WINDOWS_SIGN_TOKEN_PASSWORD;
  
  require("child_process").execSync(
    // your commande here ! For exemple and with JSign :
    `java -jar jsign-2.1.jar --keystore hardwareToken.cfg --storepass "${TOKEN_PASSWORD}" --storetype PKCS11 --tsaurl http://timestamp.digicert.com --alias "${CERTIFICATE_NAME}" "${configuration.path}"`,
    {
      stdio: "inherit"
    }
  );
};
```

--------------------------------

### Sideload AppX Package

Source: https://www.electron.build/docs/appx

Use this command to install an AppX package for enterprise distribution on supported Windows versions.

```powershell
# Enable sideloading (Windows 10 1803+, this is the default)  

# On Windows 10 S/SE, you must use the Store  

  

# Install the AppX  

Add-AppxPackage -Path ".\MyApp-1.0.0.appx"
```

--------------------------------

### Test and Uninstall AppX Locally

Source: https://www.electron.build/docs/appx

Commands for local development and cleanup. Developer Mode must be enabled on the machine to install unsigned packages.

```powershell
# Install locally (Developer Mode must be enabled for unsigned packages)  

Add-AppxPackage -Path ".\MyApp-1.0.0.appx"  

  

# Uninstall  

Get-AppxPackage | Where-Object {$_.Name -like "*MyApp*"} | Remove-AppxPackage
```

--------------------------------

### Configure npm arguments

Source: https://www.electron.build/docs/api/electron-builder.Interface.WindowsSignTaskConfiguration

Pass additional command-line arguments to the package manager during the dependency installation phase.

```json
{ "npmArgs": ["--prefer-offline", "--ignore-scripts"] }
```

--------------------------------

### Continuous Deployment Script

Source: https://www.electron.build/docs/publish

Example script configuration for publishing on every commit to non-GitHub targets like Amazon S3.

```json
"dist": "electron-builder --publish always"
```

--------------------------------

### GitHub Actions Workflow for macOS Build and Notarization

Source: https://www.electron.build/docs/features/github-actions

A GitHub Actions workflow that checks out code, sets up Node.js, installs dependencies, and then builds and notarizes the Electron application for macOS. It utilizes environment variables for code signing credentials and other necessary secrets.

```yaml
build-mac:
  runs-on: macos-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20
        cache: npm

    - name: Install dependencies
      run: npm ci

    - name: Build and notarize
      run: npx electron-builder --mac --publish always
      env:
        CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
        CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
        APPLE_ID: ${{ secrets.APPLE_ID }}
        APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
        APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Customize MSI project before compilation

Source: https://www.electron.build/docs/features/build-lifecycle

The `msiProjectCreated` hook allows modification of the WiX `.wxs` file before it is compiled into an MSI installer. This example updates the manufacturer name.

```javascript
// Edit the WiX XML before MSI compilation

msiProjectCreated: async (wixProjectPath) => {
  const fs = require("fs")
  const wxsPath = require("path").join(wixProjectPath, "installer.wxs")
  let xml = fs.readFileSync(wxsPath, "utf8")
  xml = xml.replace('Manufacturer="PLACEHOLDER"', 'Manufacturer="Acme Corp"')
  fs.writeFileSync(wxsPath, xml)
}
```

--------------------------------

### Install Pending Update

Source: https://www.electron.build/docs/features/auto-update

Explicitly triggers the installation of a pending update if one is available.

```javascript
await autoUpdater.installPendingUpdateIfAvailable()
```

--------------------------------

### Install rpm on macOS

Source: https://www.electron.build/docs/features/multi-platform-build

Installs the rpm package manager on macOS using Homebrew.

```shell
brew install rpm
```

--------------------------------

### Prepare for File Copying

Source: https://www.electron.build/docs/features/build-lifecycle

Fires before any file copying begins. The staging directory (`appOutDir`) is created but empty at this point.

```javascript
beforePack: async ({ outDir, appOutDir, packager, electronPlatformName, arch, targets }) => {
  // Generate files that need to be in the build
}
```

--------------------------------

### Install rpm on Linux

Source: https://www.electron.build/docs/features/multi-platform-build

Installs the rpm package manager on Debian/Ubuntu-based systems or RHEL/CentOS-based systems.

```shell
sudo apt-get install --no-install-recommends -y rpm
```

```shell
sudo yum install rpm-build
```

--------------------------------

### Run CLI Help for Specific Command

Source: https://www.electron.build/docs/cli

Shows how to access help documentation for specific subcommands.

```bash
./node_modules/.bin/electron-builder install-app-deps --help
```

--------------------------------

### Install FUSE dependencies for AppImage

Source: https://www.electron.build/docs/troubleshooting

Install required FUSE libraries on Linux distributions to resolve AppImage execution errors.

```bash
# Ubuntu/Debian  

sudo apt install fuse libfuse2  

  

# Fedora  

sudo dnf install fuse fuse-libs
```

--------------------------------

### Enable Auto-Launch Extension

Source: https://www.electron.build/docs/appx

Configures the app to run on user login; requires the runFullTrust capability.

```yaml
appx:  

  addAutoLaunchExtension: false    # Default: false
```

--------------------------------

### Install AppImage Maker for Electron Forge

Source: https://www.electron.build/docs/features/electron-forge

Install the AppImage maker package as a development dependency for your Electron Forge project.

```bash
npm install --save-dev electron-forge-maker-appimage
```

--------------------------------

### Install NSIS Maker for Electron Forge

Source: https://www.electron.build/docs/features/electron-forge

Install the NSIS maker package as a development dependency for your Electron Forge project.

```bash
npm install --save-dev electron-forge-maker-nsis
```

--------------------------------

### Enable NSIS Web Installer

Source: https://www.electron.build/docs/migration/v27-breaking-changes

Opt back into using the NSIS web installer by setting disableWebInstaller to false in the main process.

```typescript
import { NsisUpdater } from "electron-updater"

const updater = new NsisUpdater()

updater.disableWebInstaller = false // only if you intentionally ship a web installer
```

--------------------------------

### Build for Windows and Linux via CLI

Source: https://www.electron.build/docs/cli

Execute a build for Windows and Linux platforms using the CLI.

```bash
build -wl  
```

--------------------------------

### Default Recommended Dependencies

Source: https://www.electron.build/docs/linux

The default list of recommended package dependencies.

```json
["libappindicator3-1"]
```

--------------------------------

### Configure NSIS Web Installer Maker in forge.config.js

Source: https://www.electron.build/docs/features/electron-forge

Configure the NSIS web installer maker in your forge.config.js file. This maker extends NsisOptions.

```javascript
const { MakerNsisWeb } = require("electron-forge-maker-nsis-web")

module.exports = {
  makers: [
    new MakerNsisWeb({
      // NsisWebOptions — extends NsisOptions
    }),
  ],
}
```

--------------------------------

### Build AppX Package

Source: https://www.electron.build/docs/appx

Command to build the AppX package using electron-builder.

```bash
electron-builder --win appx
```

--------------------------------

### Electron-Builder Build Lifecycle Overview

Source: https://www.electron.build/docs/features/build-lifecycle

This diagram outlines the complete build flow of electron-builder, detailing each phase from configuration to artifact publication and the associated hooks.

```text
electron-builder build  

│  

├─ 1. Configuration & Validation  
│   └─ Load config, merge platform defaults, resolve output paths  
│  
├─ 2. For each Platform × Architecture  
│   │  
│   ├─ 2a. Install / Rebuild Native Deps  
│   │   └─ 🪝 beforeBuild  
│   │  
│   ├─ 2b. Pre-Pack  
│   │   └─ 🪝 beforePack  
│   │  
│   ├─ 2c. Extract Electron Binary → staging dir  
│   │   └─ 🪝 afterExtract  
│   │  
│   ├─ 2d. Copy App Files  
│   │   ├─ Filter via files / file patterns  
│   │   ├─ Pack node_modules (honor onNodeModuleFile)  
│   │   ├─ Create ASAR archive (if enabled)  
│   │   ├─ Copy extraResources  
│   │   └─ Copy extraFiles  
│   │  
│   ├─ 2e. Post-Pack (before signing)  
│   │   └─ 🪝 afterPack  
│   │  
│   ├─ 2f. Apply Electron Fuses (if configured)  
│   │  
│   ├─ 2g. Code Sign the .app / .exe  
│   │   └─ 🪝 afterSign  (only fires if signing actually ran)  
│   │  
│   └─ 2h. Build Distributables — For each Target  
│       ├─ 🪝 artifactBuildStarted  
│       ├─ [Target-specific build — see per-target section below]  
│       └─ 🪝 artifactBuildCompleted  
│           └─ Publish Manager schedules artifact upload  
│  
├─ 3. All Builds Complete  
│   └─ 🪝 afterAllArtifactBuild  
│  
└─ 4. Publish  
    └─ Upload all queued artifacts to configured providers  

```

--------------------------------

### Log artifact build start

Source: https://www.electron.build/docs/features/build-lifecycle

The `artifactBuildStarted` hook logs a message indicating the start of a specific artifact's build process. It provides details about the target and file being built.

```javascript
artifactBuildStarted: async ({ targetPresentableName, file, safeArtifactName, packager, arch }) => {
  
  console.log(`Starting: ${targetPresentableName}`)
}
```

--------------------------------

### NSIS Installer Image Configuration

Source: https://www.electron.build/docs/features/icons-and-images

Configure the paths for various image assets used in the NSIS installer, including header banners, sidebars, and icons. BMP files must be 24-bit RGB.

```yaml
nsis:
  installerHeader: build/installerHeader.bmp
  installerSidebar: build/installerSidebar.bmp
  uninstallerSidebar: build/uninstallerSidebar.bmp
  installerIcon: build/installerIcon.ico
  uninstallerIcon: build/uninstallerIcon.ico
```

--------------------------------

### Configure keychain partition list

Source: https://www.electron.build/docs/troubleshooting

Use this command when manually managing a keychain to ensure the build process has the necessary permissions.

```bash
security set-key-partition-list -S apple-tool:,apple: -s -k <password> <keychain>
```

--------------------------------

### Verify Universal Binary Architecture

Source: https://www.electron.build/docs/architecture

Use lipo to inspect the architecture slices of the generated application and frameworks.

```bash
# Check that both slices are present  
lipo -info dist/mac-universal/MyApp.app/Contents/MacOS/MyApp  
# Should output: Architectures in the fat file: x64 arm64  
  
# Check a framework  
lipo -info "dist/mac-universal/MyApp.app/Contents/Frameworks/Electron Framework.framework/Electron Framework"
```

--------------------------------

### Build and Publish Linux Snapcraft Package

Source: https://www.electron.build/docs/features/github-actions

A GitHub Actions step to build and publish an Electron application as a Linux Snapcraft package. Requires Snapcraft store credentials and a GitHub token to be set as secrets.

```yaml
- name: Build and publish Snap
  run: npx electron-builder --linux snap --publish always
  env:
    SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }}
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
```

--------------------------------

### Display FUSE2 Error Message

Source: https://www.electron.build/docs/appimage

Example of the error encountered when FUSE2 is missing on modern Linux distributions.

```text
dlopen(): error loading libfuse.so.2  

AppImages require FUSE to run.  
```

--------------------------------

### Define Build Configuration

Source: https://www.electron.build/docs

Add the build configuration block to your package.json file.

```json
"build": {  

  "appId": "your.id",  

  "mac": {  

    "category": "your.app.category.type"  

  }  

}
```

--------------------------------

### Test the built AppImage

Source: https://www.electron.build/docs/appimage

Set execution permissions and run the AppImage. The --no-sandbox flag may be necessary on distributions with restricted user namespaces.

```bash
chmod +x dist/MyApp-1.0.0.AppImage  

./dist/MyApp-1.0.0.AppImage --no-sandbox  
```

--------------------------------

### Configure build targets and architectures

Source: https://www.electron.build/docs/cli

Define platform-specific targets and architectures using various configuration file formats.

```json
"build": {  

  "win": {  

    "target": [  

      {  

        "target": "nsis",  

        "arch": [  

          "x64",  

          "arm64"  

        ]  

      }  

    ]  

  },  

  "mac": {  

    "target": [  

      {  

        "target": "dmg",  

        "arch": [  

          "universal"  

        ]  

      }  

    ]  

  }  

}  
```

```yaml
win:  

  target:  

    - target: nsis  

      arch:  

        - x64  

        - arm64  

mac:  

  target:  

    - target: dmg  

      arch: universal  
```

```javascript
module.exports = {  

  "win": {  

    "target": [  

      {  

        "target": "nsis",  

        "arch": [  

          "x64",  

          "arm64"  

        ]  

      }  

    ]  

  },  

  "mac": {  

    "target": [  

      {  

        "target": "dmg",  

        "arch": [  

          "universal"  

        ]  

      }  

    ]  

  }  

}  
```

--------------------------------

### AppImage Environment Variable Log Error

Source: https://www.electron.build/docs/features/auto-update

Example of the log message indicating that the APPIMAGE environment variable is missing.

```text
APPIMAGE env is not defined, current application is not an AppImage
```

--------------------------------

### Build Universal Binaries

Source: https://www.electron.build/docs/architecture

Commands and configuration to generate universal binaries for macOS.

```bash
electron-builder --mac --universal
```

```yaml
mac:  
  target:  
    - target: dmg  
      arch: universal
```

--------------------------------

### List macOS code signing identities

Source: https://www.electron.build/docs/troubleshooting

Run this command to verify which Developer ID certificates are currently installed on the system.

```bash
security find-identity -v -p codesigning
```

--------------------------------

### Customize Linux Desktop Entry

Source: https://www.electron.build/docs/linux

Define application metadata and desktop actions in the linux.desktop configuration block.

```yaml
linux:  

  desktop:  

    entry:  

      Name: My Application  

      Comment: A fantastic application  

      Categories: Office;Productivity  

      Keywords: productivity;notes;organizer  

      StartupWMClass: my-app       # helps window managers match window to icon  

      Terminal: false  

      Type: Application  

    desktopActions:  

      NewWindow:  

        Name: New Window  

        Exec: my-app --new-window  

      NewFile:  

        Name: New File  

        Exec: my-app --new-file
```

--------------------------------

### Build Windows ARM64

Source: https://www.electron.build/docs/architecture

Command to build an Electron application for Windows ARM64 architecture.

```bash
electron-builder --win --arm64
```

--------------------------------

### Publish to Local Minio

Source: https://www.electron.build/docs/tutorials/test-update-on-s3-locally

Use this command to publish your application artifacts to a local Minio instance. Ensure your Minio credentials and endpoint are correctly set as environment variables or within your configuration.

```bash
electron-builder --publish always \
  --config.publish.provider=s3 \
  --config.publish.endpoint=http://localhost:9000 \
  --config.publish.bucket=test-bucket
```

--------------------------------

### Run Electron build container with Wine

Source: https://www.electron.build/docs/features/multi-platform-build

Executes a Docker container for building Windows targets on any platform. It mounts the current directory and caches, and sets environment variables for the build process.

```shell
docker run --rm -ti \
  --env-file <(env | grep -iE 'DEBUG|NODE_|ELECTRON_|YARN_|NPM_|CI|CSC_|GH_|GITHUB_|BT_|AWS_|STRIP|BUILD_') \
  --env ELECTRON_CACHE="/root/.cache/electron" \
  --env ELECTRON_BUILDER_CACHE="/root/.cache/electron-builder" \
  -v ${PWD}:/project \
  -v ${PWD##*/}-node-modules:/project/node_modules \
  -v ~/.cache/electron:/root/.cache/electron \
  -v ~/.cache/electron-builder:/root/.cache/electron-builder \
  electronuserland/builder:wine
```

--------------------------------

### macOS DMG Configuration

Source: https://www.electron.build/docs/features/icons-and-images

Configure the background image, background color, and icon for your macOS DMG installer. Ensure image dimensions match window dimensions for a polished look.

```yaml
dmg:
  background: build/background.png
  backgroundColor: "#ffffff"   # fallback if no background image
  icon: build/dmg-icon.icns    # volume badge icon (optional)
  iconSize: 80
  iconTextSize: 12
```

--------------------------------

### Customize AppX manifest before packaging

Source: https://www.electron.build/docs/features/build-lifecycle

Use the `appxManifestCreated` hook to modify the `AppxManifest.xml` file before the AppX or MSIX package is created. This example changes the application's display name.

```javascript
// Edit the AppX manifest before packaging

appxManifestCreated: async (manifestPath) => {
  const fs = require("fs")
  let manifest = fs.readFileSync(manifestPath, "utf8")
  manifest = manifest.replace(/<DisplayName>.*?<\/DisplayName>/, "<DisplayName>My App</DisplayName>")
  fs.writeFileSync(manifestPath, manifest)
}
```

--------------------------------

### Configure Custom Code Signing

Source: https://www.electron.build/docs/win

Use the sign option in the win configuration to point to a custom signing script.

```json
"win": {  

  "signtoolOptions": {  

    "sign": "./customSign.js"  

  }  

}  
```

--------------------------------

### Remove framework and version settings

Source: https://www.electron.build/docs/migration/v27-breaking-changes

Remove framework, nodeVersion, and launchUiVersion as they are no longer supported or have no effect.

```json
{  

  "build": {  

    "framework": "electron",    // ← delete; "electron" was and remains the default  

    "nodeVersion": "current",   // ← delete; no effect  

    "launchUiVersion": "0.1.0"  // ← delete; no effect  

  }  

}  
```

--------------------------------

### Upload debug symbols and return extra files

Source: https://www.electron.build/docs/features/build-lifecycle

The `afterAllArtifactBuild` hook executes after all artifacts are built. This example demonstrates uploading debug symbols to Sentry and returning an additional changelog file for publishing.

```javascript
afterAllArtifactBuild: async ({ outDir, artifactPaths, platformToTargets, configuration }) => {
  
  // Upload debug symbols

  const dsymPaths = artifactPaths.filter(p => p.endsWith(".dSYM"))
  for (const p of dsymPaths) {
    await uploadToSentry(p)
  }
  
  // Return extra files to include in the publish step

  const changelog = `${outDir}/CHANGELOG.md`
  writeChangelog(changelog)
  return [changelog]
}
```

--------------------------------

### CLI Publish Option

Source: https://www.electron.build/docs/publish

Displays the available choices for the --publish flag in the electron-builder CLI.

```text


Publishing:  

  --publish, -p  [choices: "onTag", "onTagOrDraft", "always", "never"]  



```

--------------------------------

### Set Auto-Update Channel in Application

Source: https://www.electron.build/docs/tutorials/release-using-channels

In your Electron application, set the 'autoUpdater.channel' property to specify which release channel users should receive updates from. This determines whether users get 'latest', 'beta', or 'alpha' versions.

```javascript
autoUpdater.channel = "beta"
```

--------------------------------

### Recommended build/ directory layout for icons and images

Source: https://www.electron.build/docs/features/icons-and-images

This structure shows the recommended placement of icon and image assets within the 'build/' directory for electron-builder. It includes master icons, platform-specific icons, and assets for macOS DMG backgrounds.

```plaintext
build/  

├── icon.svg            ← master icon (SVG — scales perfectly to all sizes)  

├── icon.png            ← or use PNG (1024×1024 recommended)  

├── icon.icns           ← optional: pre-built macOS icon (skips conversion)  

├── icon.ico            ← optional: pre-built Windows icon (skips conversion)  

├── background.png      ← macOS DMG background (540×380 px)  

├── background@2x.png   ← Retina DMG background (1080×760 px)  

└── icons/              ← optional: manual Linux PNG set  
    ├── 16x16.png  
    ├── 32x32.png  
    └── 512x512.png  
```

--------------------------------

### Run Electron Builder via npx

Source: https://www.electron.build/docs/cli

Executes electron-builder using npx, which is bundled with Node.js.

```bash
npx electron-builder
```

--------------------------------

### Ensuring Native Module Rebuilding

Source: https://www.electron.build/docs/features/github-actions

Resolve 'Cannot find module' errors by ensuring native modules are rebuilt for the target Electron version. Use `npm ci` instead of `npm install` for reliable dependency management and automatic native module rebuilding by electron-builder.

```bash
npm ci
```

--------------------------------

### Simple include configuration

Source: https://www.electron.build/docs/contents

Exclude specific file types and directories while including all other files.

```yaml
files:  

  - "**/*"  

  - "!src/**"  

  - "!*.ts"  

  - "!tsconfig*.json"  
```
Tokens:
Raw