or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-electron-builder-squirrel-windows

Plugin for electron-builder to build Squirrel.Windows installer

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/electron-builder-squirrel-windows@26.0.x

To install, run

npx @tessl/cli install tessl/npm-electron-builder-squirrel-windows@26.0.0

index.mddocs/

Electron Builder Squirrel Windows

Electron 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.

Package Information

  • Package Name: electron-builder-squirrel-windows
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install electron-builder-squirrel-windows
  • Main Entry: out/SquirrelWindowsTarget.js
  • TypeScript Types: out/SquirrelWindowsTarget.d.ts
  • Published Files: out/ directory, template.nuspectemplate

Core Imports

import 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");

Basic Usage

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
    }
  }
}

Architecture

The package is built around a single main component:

  • SquirrelWindowsTarget Class: Extends the base Target class from app-builder-lib, implementing the Squirrel.Windows installer generation process
  • Build Pipeline: Handles package validation, vendor directory preparation, stub executable generation, and installer creation
  • Signing Integration: Integrates with electron-builder's code signing functionality for both the application and installer

Capabilities

Squirrel Windows Target

Main 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>;
}

Build Method

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:

  • Setup file naming and path resolution
  • Vendor directory preparation and signing
  • Stub executable generation
  • Windows installer creation via electron-winstaller
  • MSI generation (if configured)
  • Artifact emission for packaging pipeline

Distribution Options Computation

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:

  • electron-builder configuration
  • Platform-specific build options
  • Default values and computed properties
  • Repository information for automatic iconUrl generation

Private Methods

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 Types

SquirrelWindowsOptions

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;
}

Architecture Types

/** 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;
}

Error Handling

Configuration Validation

The package validates configuration options and throws InvalidConfigurationError for:

  • Missing required iconUrl when not automatically derivable from GitHub repository: "squirrelWindows.iconUrl is not specified, please see https://www.electron.build/squirrel-windows#SquirrelWindowsOptions-iconUrl"
  • Conflicting options that are managed internally: outputDirectory, appDirectory, exe, fixUpPaths, usePackageJson, extraFileSpecs, extraMetadataSpecs, skipUpdateIcon, setupExe
  • Invalid msi option type: "msi expected to be boolean value, but string '[value]' was specified"
  • Deprecated noMsi option (shows warning, automatically converts to msi: !noMsi)

Build Process Errors

Common build failures include:

  • Missing application executable: "App executable not found in app directory: [path]"
  • Squirrel.exe not found in vendor directory (results in warning: "Squirrel.exe not found in vendor directory, skipping signing")
  • Custom vendor directory not accessible (warning: "unable to access custom Squirrel.Windows vendor directory, falling back to default vendor")
  • Code signing failures for vendor executables or final installer
  • Wine execution failures when building on non-Windows platforms

Dependencies

Required Dependencies

  • electron-winstaller: 5.4.0 - Core Windows installer creation functionality
  • app-builder-lib: workspace dependency - Base Target class and utilities
  • builder-util: workspace dependency - Logging, validation, and utility functions

Peer Dependencies

  • electron-builder: The main electron-builder package that uses this plugin
  • mono: Required on macOS for cross-platform building to Windows

Build Artifacts

The package generates several build artifacts during the installer creation process:

  • Setup executable (e.g., MyApp Setup 1.0.0.exe) - Main installer file
  • MSI installer (optional, when msi: true) - Windows Installer format
  • NuGet packages:
    • MyApp-1.0.0-full.nupkg - Complete application package
    • MyApp-1.0.0-delta.nupkg - Delta update package (when remoteReleases configured)
  • RELEASES file - Contains package metadata for Squirrel updates

Usage Notes

  • This target is deprecated in favor of NSIS but remains maintained
  • Applications must handle Squirrel.Windows startup events
  • Requires mono installation on macOS (brew install mono) for cross-platform builds
  • Creates both full and delta update packages when remoteReleases is configured
  • Supports custom vendor directories for modified Squirrel.Windows distributions
  • Integrates with electron-builder's code signing pipeline for security compliance
  • Uses patched version of Squirrel.Windows from electron-builder-binaries for enhanced compatibility
  • Template file template.nuspectemplate is used for NuGet package generation