electron-squirrel-startup

A modern, ESM-compatible version of electron-squirrel-startup for handling Squirrel.Windows events in Electron applications.

Features

• ✅ Full ESM Support - Works with both CommonJS and ES modules
• ✅ TypeScript First - Written in TypeScript with full type definitions
• ✅ Modern APIs - Promise-based async functions alongside sync compatibility
• ✅ Better Error Handling - Proper error types and timeout handling
• ✅ Configurable - Customizable options for update paths and timeouts
• ✅ Backwards Compatible - Drop-in replacement for the original package

Installation

# With npm
npm install @electronfriends/electron-squirrel-startup

# With yarn
yarn add @electronfriends/electron-squirrel-startup

# With pnpm
pnpm add @electronfriends/electron-squirrel-startup

Usage

Simple Usage (Drop-in Replacement)

Replace your existing electron-squirrel-startup import:

// CommonJS (legacy)
const squirrelStartup = require('@electronfriends/electron-squirrel-startup');
if (squirrelStartup) {
  // App was handling a squirrel event and has quit
  return;
}

// ESM (modern)
import squirrelStartup from '@electronfriends/electron-squirrel-startup';
if (squirrelStartup) {
  // App was handling a squirrel event and has quit
  return;
}

Advanced Usage with Modern APIs

// ESM with async/await
import { handleSquirrelEvent, SquirrelCommand, SquirrelError } from '@electronfriends/electron-squirrel-startup';
import { app } from 'electron';

async function main() {
  try {
    const wasHandled = await handleSquirrelEvent({
      timeout: 15000, // 15 second timeout
      detached: true  // Run update process detached
    });
    
    if (wasHandled) {
      console.log('Squirrel event was handled, quitting app');
      app.quit();
      return;
    }
    
    // Continue with normal app initialization
    console.log('No squirrel events, starting app normally');
    
  } catch (error) {
    if (error instanceof SquirrelError) {
      console.error('Squirrel operation failed:', error.message);
      console.error('Command:', error.command);
      console.error('Exit code:', error.exitCode);
    }
    app.quit();
  }
}

main();

TypeScript Usage

import { 
  handleSquirrelEvent, 
  handleSquirrelEventSync,
  SquirrelOptions, 
  SquirrelCommand, 
  SquirrelError 
} from '@electronfriends/electron-squirrel-startup';

const options: SquirrelOptions = {
  updateExePath: 'C:\\Custom\\Path\\Update.exe',
  timeout: 20000,
  detached: true
};

// Async version
const handled = await handleSquirrelEvent(options);

// Sync version (auto-quits on squirrel events)
const shouldQuit = handleSquirrelEventSync(options);

API Reference

Functions

handleSquirrelEvent(options?: SquirrelOptions): Promise<boolean>

Handles Squirrel.Windows events asynchronously. Returns a promise that resolves to true if a squirrel event was handled, false otherwise.

handleSquirrelEventSync(options?: SquirrelOptions): boolean

Handles Squirrel.Windows events synchronously and automatically quits the app if an event was handled. Returns true if a squirrel event was handled, false otherwise.

Types

SquirrelOptions

interface SquirrelOptions {
  /** Custom path to Update.exe (optional) */
  updateExePath?: string;
  /** Timeout for update operations in milliseconds (default: 10000) */
  timeout?: number;
  /** Whether to run update operations detached (default: true) */
  detached?: boolean;
}

SquirrelCommand

enum SquirrelCommand {
  INSTALL = '--squirrel-install',
  UPDATED = '--squirrel-updated',
  UNINSTALL = '--squirrel-uninstall',
  OBSOLETE = '--squirrel-obsolete',
}

SquirrelError

Custom error class for squirrel operation failures:

class SquirrelError extends Error {
  constructor(
    message: string, 
    public readonly command: string, 
    public readonly exitCode?: number
  );
}

Supported Commands

• --squirrel-install - App was just installed
• --squirrel-updated - App was just updated
• --squirrel-uninstall - App is being uninstalled
• --squirrel-obsolete - App version is obsolete

Migration from electron-squirrel-startup

This package is designed as a drop-in replacement. Simply replace the package name in your imports:

- const squirrelStartup = require('electron-squirrel-startup');
+ const squirrelStartup = require('@electronfriends/electron-squirrel-startup');

- import squirrelStartup from 'electron-squirrel-startup';
+ import squirrelStartup from '@electronfriends/electron-squirrel-startup';

Credits

This package is based on the original electron-squirrel-startup by MongoDB.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.