A modern TypeScript library for handling Squirrel.Windows events in Electron applications
npm install @electronfriends/electron-squirrel-startupbash
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';
``