Plugin for electron-builder to build Squirrel.Windows installer
npx @tessl/cli install tessl/npm-electron-builder-squirrel-windows@26.0.0Electron Builder Squirrel Windows is a plugin for electron-builder that creates Squirrel.Windows installers for Electron applications. It provides a specialized target implementation for generating Windows installers with automatic update capabilities using the Squirrel.Windows framework.
npm install electron-builder-squirrel-windowsout/SquirrelWindowsTarget.jsout/SquirrelWindowsTarget.d.tsout/ directory, template.nuspectemplateimport SquirrelWindowsTarget from "electron-builder-squirrel-windows";
import { SquirrelWindowsOptions } from "app-builder-lib";For CommonJS:
const SquirrelWindowsTarget = require("electron-builder-squirrel-windows");
const { SquirrelWindowsOptions } = require("app-builder-lib");This package is typically used as part of the electron-builder configuration and not directly instantiated by developers. Electron-builder automatically uses this target when squirrelWindows is configured:
// In your electron-builder configuration
{
"build": {
"win": {
"target": [
{
"target": "squirrel",
"arch": ["x64"]
}
]
},
"squirrelWindows": {
"iconUrl": "https://example.com/icon.ico",
"loadingGif": "build/install-spinner.gif",
"msi": true
}
}
}The package is built around a single main component:
Target class from app-builder-lib, implementing the Squirrel.Windows installer generation processMain target class for building Squirrel.Windows installers with full integration into the electron-builder ecosystem.
export default class SquirrelWindowsTarget extends Target {
readonly options: SquirrelWindowsOptions;
isAsyncSupported: boolean;
constructor(packager: WinPackager, outDir: string);
build(appOutDir: string, arch: Arch): Promise<void>;
computeEffectiveDistOptions(
appDirectory: string,
outputDirectory: string,
setupFile: string
): Promise<SquirrelOptions>;
}Executes the complete Squirrel.Windows installer build process including signing and artifact generation.
/**
* Build Squirrel.Windows installer for the specified architecture
* @param appOutDir - Directory containing built Electron application
* @param arch - Target architecture (x64, ia32, arm64)
*/
async build(appOutDir: string, arch: Arch): Promise<void>;Usage: This method is called automatically by electron-builder and handles:
Computes the effective configuration options for the electron-winstaller library.
/**
* Compute effective distribution options for electron-winstaller
* @param appDirectory - Application directory path
* @param outputDirectory - Installer output directory
* @param setupFile - Setup executable filename
* @returns Promise resolving to SquirrelOptions for electron-winstaller
*/
async computeEffectiveDistOptions(
appDirectory: string,
outputDirectory: string,
setupFile: string
): Promise<SquirrelOptions>;Usage: This method merges configuration from multiple sources:
The following private methods handle internal operations:
/**
* Prepare and sign the Squirrel.Windows vendor directory
* @returns Promise resolving to temporary vendor directory path
*/
private async prepareSignedVendorDirectory(): Promise<string>;
/**
* Generate stub executable for the application
* @param appOutDir - Application output directory
* @param vendorDir - Vendor directory path
*/
private async generateStubExecutableExe(appOutDir: string, vendorDir: string): Promise<void>;
/**
* Select appropriate 7zip executable for host architecture
* @param vendorDirectory - Vendor directory path
*/
private select7zipArch(vendorDirectory: string): void;
/**
* Create nuspec template with project URL
* @returns Promise resolving to template file path
*/
private async createNuspecTemplateWithProjectUrl(): Promise<string>;
/**
* Get application name from options or packager
*/
private get appName(): string;
/**
* Get executable name from packager info
*/
private get exeName(): string;Configuration interface for Squirrel.Windows target options.
interface SquirrelWindowsOptions extends TargetSpecificOptions {
/** URL to ICO file for application icon (displayed in Control Panel) */
readonly iconUrl?: string | null;
/** Path to GIF file displayed during install */
readonly loadingGif?: string | null;
/** Whether to create MSI installer (default: false) */
readonly msi?: boolean;
/** URL for existing updates or true for automatic GitHub detection */
readonly remoteReleases?: string | boolean | null;
/** Authentication token for remote updates */
readonly remoteToken?: string | null;
/** Use appId instead of name for package identification */
readonly useAppIdAsId?: boolean;
/** Custom Squirrel vendor directory path */
readonly customSquirrelVendorDir?: string;
/** Package name override */
readonly name?: string;
}/** Target architecture enumeration */
enum Arch {
ia32,
x64,
armv7l,
arm64,
universal
}
type ArchType = "x64" | "ia32" | "armv7l" | "arm64" | "universal";
/** Base Target class from app-builder-lib */
abstract class Target {
abstract readonly outDir: string;
abstract readonly options: TargetSpecificOptions | null;
readonly buildQueueManager: AsyncTaskManager;
readonly name: string;
readonly isAsyncSupported: boolean;
constructor(name: string, isAsyncSupported?: boolean);
abstract build(appOutDir: string, arch: Arch): Promise<any>;
async checkOptions(): Promise<any>;
async finishBuild(): Promise<any>;
}
/** Windows packager interface */
interface WinPackager {
// Simplified interface - full definition in app-builder-lib
appInfo: AppInfo;
platformSpecificBuildOptions: any;
config: Configuration;
sign(file: string): Promise<void>;
signAndEditResources(file: string, arch: Arch, outDir: string): Promise<void>;
expandArtifactNamePattern(options: any, ext: string, arch: Arch, pattern: string): string;
info: BuildInfo;
projectDir: string;
buildResourcesDir: string;
resourceList: Promise<string[]>;
}
/** Squirrel options for electron-winstaller */
interface SquirrelOptions {
appDirectory: string;
outputDirectory: string;
name: string;
title: string;
version: string;
description: string;
exe: string;
authors: string;
iconUrl: string;
copyright?: string;
loadingGif?: string;
noMsi?: boolean;
usePackageJson?: boolean;
vendorDirectory?: string;
fixUpPaths?: boolean;
setupExe?: string;
setupMsi?: string;
remoteReleases?: string;
remoteToken?: string;
nuspecTemplate?: string;
}The package validates configuration options and throws InvalidConfigurationError for:
iconUrl when not automatically derivable from GitHub repository: "squirrelWindows.iconUrl is not specified, please see https://www.electron.build/squirrel-windows#SquirrelWindowsOptions-iconUrl"outputDirectory, appDirectory, exe, fixUpPaths, usePackageJson, extraFileSpecs, extraMetadataSpecs, skipUpdateIcon, setupExemsi option type: "msi expected to be boolean value, but string '[value]' was specified"noMsi option (shows warning, automatically converts to msi: !noMsi)Common build failures include:
5.4.0 - Core Windows installer creation functionalityThe package generates several build artifacts during the installer creation process:
MyApp Setup 1.0.0.exe) - Main installer filemsi: true) - Windows Installer formatMyApp-1.0.0-full.nupkg - Complete application packageMyApp-1.0.0-delta.nupkg - Delta update package (when remoteReleases configured)mono installation on macOS (brew install mono) for cross-platform buildsremoteReleases is configuredelectron-builder-binaries for enhanced compatibilitytemplate.nuspectemplate is used for NuGet package generation