Registry / devops / electron-builder-squirrel-windows

electron-builder-squirrel-windows

library26.8.1jsnpmunverified

electron-builder-squirrel-windows is a plugin for electron-builder that facilitates the creation of Squirrel.Windows installers for Electron applications. This enables developers to package their Electron apps into a format suitable for automatic updates and user-friendly installation on Windows systems. The current stable version is 26.8.1, aligning with the electron-builder major version. electron-builder and its ecosystem, including this plugin, maintain an active release cadence, often issuing patch and minor updates in response to bug fixes or Electron framework advancements. Its primary differentiator is its seamless integration within the comprehensive electron-builder toolchain, offering a streamlined approach to multi-platform application packaging, particularly for Windows auto-updates and silent installations, compared to direct Squirrel.Windows usage.

devops

npm install electron-builder-squirrel-windows

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ELECTRON-BUILDER-S

electron-builder-squirrel-windows

devopsjavascriptv26.8.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

build

✓ import { build } from 'electron-builder'

While electron-builder-squirrel-windows is a plugin, its functionality is typically invoked through `electron-builder`'s programmatic API or CLI. This import is for programmatically triggering an Electron build that can use this plugin via configuration.

Configuration

✓ import { Configuration } from 'electron-builder'

For TypeScript users, importing `Configuration` from `electron-builder` allows for type-checking the `build` configuration object, which includes the `squirrelWindows` options provided by this plugin.

SquirrelWindowsOptions

✓ import { SquirrelWindowsOptions } from 'electron-builder-squirrel-windows'

This interface defines the specific options available for the `squirrelWindows` configuration key within `electron-builder`. While not directly imported for runtime logic, it's useful for type safety and understanding available options when configuring the builder.

This `package.json` snippet demonstrates how to configure `electron-builder` to generate a Squirrel.Windows installer. It includes defining the `appId`, `productName`, output directory, and specific Squirrel.Windows options like `certificateFile` and `certificatePassword` for code signing. The `build:win` script invokes `electron-builder` to create the Windows executable.

{ "name": "my-electron-app", "version": "1.0.0", "main": "dist/main.js", "scripts": { "postinstall": "electron-builder install-app-deps", "build:win": "electron-builder --win --x64" }, "devDependencies": { "electron": "^29.0.0", "electron-builder": "^26.0.0", "electron-builder-squirrel-windows": "^26.0.0", "typescript": "^5.0.0" }, "build": { "appId": "com.example.myapp", "productName": "My Electron App", "directories": { "output": "release" }, "win": { "target": [ { "target": "squirrel", "arch": [ "x64" ] } ], "icon": "build/icon.ico" }, "squirrelWindows": { "artifactName": "${productName}Setup-${version}.${ext}", "loadingGif": "build/installer-loading.gif", "certificateFile": "./build/cert.pfx", "certificatePassword": "" // Use process.env.CERT_PASSWORD ?? '' in a real project } } }

Debug

Known issues

deprecatedThe Squirrel.Windows target is maintained but officially deprecated by electron-builder in favor of NSIS. While still functional, users are encouraged to consider NSIS for new projects or when migrating.

fix

For new projects, evaluate using the `nsis` target in your `electron-builder` configuration. If migrating, review NSIS documentation for equivalent options.

affects: >=26.0.0

breakingSecurity updates to the `tar` dependency in `electron-builder` (which this plugin relies on) may necessitate updating `electron-builder` to ensure all components are secure. Older versions of `tar` had known vulnerabilities.

fix

Regularly update `electron-builder` and its plugins to their latest patch versions to incorporate security fixes. Run `npm update electron-builder electron-builder-squirrel-windows`.

affects: <26.9.0

gotchaBuilding Squirrel.Windows installers on macOS or Linux requires `mono` to be installed. Without it, the build process will fail.

fix

On macOS, install mono via Homebrew: `brew install mono`. On Linux, ensure `mono` and `wine` are installed and configured.

affects: >=1.0.0

gotchaFor Squirrel.Windows to function correctly with auto-updates and installer events (like first run or uninstall), your Electron app must explicitly handle Squirrel.Windows startup events. This often involves using `electron-squirrel-startup` in your main process.

fix

Include `if (require('electron-squirrel-startup')) return;` at the very beginning of your main Electron process file (e.g., `main.js`) to handle these events gracefully.

affects: >=1.0.0

gotchaCode signing is mandatory for production Squirrel.Windows installers. Failing to provide valid `certificateFile` and `certificatePassword` will result in unsigned installers, which trigger security warnings for users and may prevent installation.

fix

Obtain a code signing certificate (`.pfx` file), and configure `squirrelWindows.certificateFile` and `squirrelWindows.certificatePassword` in your `electron-builder` configuration. Consider using environment variables for the password in CI/CD.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Description is required.

The `description` field in your project's `package.json` is either missing or empty. Squirrel.Windows relies on this metadata for its `.nuspec` manifest.

fix

Ensure your `package.json` contains a non-empty `description` field, e.g., `"description": "My awesome Electron application."`

Error: Cannot find module 'builder-util' (or 'app-builder-lib', 'read-config-file', etc.)

Specific internal `electron-builder` dependencies are missing during the build process. This can occur due to aggressive package manager optimizations (like `.yarnclean` files), or corrupted `node_modules`.

fix

Ensure `node_modules` is correctly installed by deleting `node_modules` and `package-lock.json`/`yarn.lock`, then reinstalling dependencies. If using Yarn PnP, configure `nodeLinker: "node-modules"` in `.yarnrc.yaml`.

Error: Exit code: 255. Command failed: mono ... Update-Mono.exe ... wine: cannot find L"C:\windows\system32\.7z.exe"

This error typically occurs when attempting to build Squirrel.Windows installers on a non-Windows machine (macOS/Linux) without the necessary `mono` and `wine` setup, or if internal tools like `7z.exe` are not found in the expected cache location.

fix

Verify `mono` is installed and accessible in your PATH. If running on Linux, also ensure `wine` is installed. Check `~/.cache/electron-builder/Squirrel.Windows/` for the integrity of downloaded Squirrel.Windows tools and binaries. Clearing the cache might help (`rm -rf ~/.cache/electron-builder`).

The 'win.icon' option requires a path to a .ico file. Please specify it.

The icon path specified under `win.icon` in your `electron-builder` configuration is either incorrect, the file is missing, or it's not a `.ico` format.

fix

Ensure the path to `build/icon.ico` is correct and the file exists. It must be a Windows ICO file. If you were previously using `iconUrl` directly in `build` and upgraded, ensure it's now under `squirrelWindows.iconUrl` or `win.icon` with a local path.

Upgrade

Version history

26.8.1latest on npm

Audit

Dependencies

electron-builderrequiredThis package is a plugin for electron-builder, extending its functionality to produce Squirrel.Windows installers.

electron-winstallerrequiredCore dependency used internally by the plugin to generate Squirrel.Windows artifacts.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/electron-userland/electron-builder ↗

packagehttps://www.npmjs.com/package/electron-builder-squirrel-windows ↗

homepagehttps://www.electron.build ↗