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

``bash

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

$3

Replace your existing electron-squirrel-startup import:

`javascript
// 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;
}
`

$3

`javascript
// 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();
`

$3

`typescript
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

$3

#### handleSquirrelEvent(options?: SquirrelOptions): Promise

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.

$3

#### SquirrelOptions

`typescript
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

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

#### SquirrelError

Custom error class for squirrel operation failures:

`typescript
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:

`diff
- 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.