{"id":13110,"library":"electron-builder-squirrel-windows","title":"Electron Builder Squirrel.Windows Plugin","description":"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.","status":"active","version":"26.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/electron-userland/electron-builder","tags":["javascript","typescript"],"install":[{"cmd":"npm install electron-builder-squirrel-windows","lang":"bash","label":"npm"},{"cmd":"yarn add electron-builder-squirrel-windows","lang":"bash","label":"yarn"},{"cmd":"pnpm add electron-builder-squirrel-windows","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for electron-builder, extending its functionality to produce Squirrel.Windows installers.","package":"electron-builder","optional":false},{"reason":"Core dependency used internally by the plugin to generate Squirrel.Windows artifacts.","package":"electron-winstaller","optional":false}],"imports":[{"note":"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.","symbol":"build","correct":"import { build } from 'electron-builder'"},{"note":"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.","symbol":"Configuration","correct":"import { Configuration } from 'electron-builder'"},{"note":"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.","symbol":"SquirrelWindowsOptions","correct":"import { SquirrelWindowsOptions } from 'electron-builder-squirrel-windows'"}],"quickstart":{"code":"{\n  \"name\": \"my-electron-app\",\n  \"version\": \"1.0.0\",\n  \"main\": \"dist/main.js\",\n  \"scripts\": {\n    \"postinstall\": \"electron-builder install-app-deps\",\n    \"build:win\": \"electron-builder --win --x64\"\n  },\n  \"devDependencies\": {\n    \"electron\": \"^29.0.0\",\n    \"electron-builder\": \"^26.0.0\",\n    \"electron-builder-squirrel-windows\": \"^26.0.0\",\n    \"typescript\": \"^5.0.0\"\n  },\n  \"build\": {\n    \"appId\": \"com.example.myapp\",\n    \"productName\": \"My Electron App\",\n    \"directories\": {\n      \"output\": \"release\"\n    },\n    \"win\": {\n      \"target\": [\n        {\n          \"target\": \"squirrel\",\n          \"arch\": [\n            \"x64\"\n          ]\n        }\n      ],\n      \"icon\": \"build/icon.ico\"\n    },\n    \"squirrelWindows\": {\n      \"artifactName\": \"${productName}Setup-${version}.${ext}\",\n      \"loadingGif\": \"build/installer-loading.gif\",\n      \"certificateFile\": \"./build/cert.pfx\",\n      \"certificatePassword\": \"\" // Use process.env.CERT_PASSWORD ?? '' in a real project\n    }\n  }\n}","lang":"json","description":"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."},"warnings":[{"fix":"For new projects, evaluate using the `nsis` target in your `electron-builder` configuration. If migrating, review NSIS documentation for equivalent options.","message":"The 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.","severity":"deprecated","affected_versions":">=26.0.0"},{"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`.","message":"Security 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.","severity":"breaking","affected_versions":"<26.9.0"},{"fix":"On macOS, install mono via Homebrew: `brew install mono`. On Linux, ensure `mono` and `wine` are installed and configured.","message":"Building Squirrel.Windows installers on macOS or Linux requires `mono` to be installed. Without it, the build process will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Code 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your `package.json` contains a non-empty `description` field, e.g., `\"description\": \"My awesome Electron application.\"`","cause":"The `description` field in your project's `package.json` is either missing or empty. Squirrel.Windows relies on this metadata for its `.nuspec` manifest.","error":"Error: Description is required."},{"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`.","cause":"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`.","error":"Error: Cannot find module 'builder-util' (or 'app-builder-lib', 'read-config-file', etc.)"},{"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`).","cause":"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.","error":"Error: Exit code: 255. Command failed: mono ... Update-Mono.exe ... wine: cannot find L\"C:\\windows\\system32\\.7z.exe\""},{"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.","cause":"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.","error":"The 'win.icon' option requires a path to a .ico file. Please specify it."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}