CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-electron-builder-squirrel-windows

Plugin for electron-builder to build Squirrel.Windows installer

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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

Install with Tessl CLI

npx tessl i tessl/npm-electron-builder-squirrel-windows

docs

index.md

tile.json