0
# Update Electron App
1

2
Update Electron App is a drop-in module that adds autoUpdating capabilities to Electron applications. It provides seamless integration with minimal configuration, supporting multiple update sources including the free update.electronjs.org service and static file storage solutions like S3.
3

4
## Package Information
5

6
- **Package Name**: update-electron-app
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install update-electron-app`
10

11
## Core Imports
12

13
```typescript
14
import { updateElectronApp, makeUserNotifier, UpdateSourceType } from "update-electron-app";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { updateElectronApp, makeUserNotifier, UpdateSourceType } = require("update-electron-app");
21
```
22

23
Note: This package is designed for use within Electron applications, so Electron types (like `Electron.Event`) are available in the runtime environment.
24

25
## Basic Usage
26

27
```typescript
28
import { updateElectronApp, UpdateSourceType } from "update-electron-app";
29

30
// Simple setup with default configuration
31
updateElectronApp();
32

33
// Custom configuration with update.electronjs.org
34
updateElectronApp({
35
  updateSource: {
36
    type: UpdateSourceType.ElectronPublicUpdateService,
37
    repo: 'owner/repo'
38
  },
39
  updateInterval: '1 hour',
40
  notifyUser: true
41
});
42

43
// Static storage configuration
44
updateElectronApp({
45
  updateSource: {
46
    type: UpdateSourceType.StaticStorage,
47
    baseUrl: 'https://my-bucket.s3.amazonaws.com/my-app-updates'
48
  }
49
});
50
```
51

52
## Architecture
53

54
Update Electron App is built around several key components:
55

56
- **Update Sources**: Supports both Electron's public update service and static file storage
57
- **Automatic Checking**: Configurable intervals for checking updates (minimum 5 minutes)
58
- **Background Downloads**: Downloads updates without blocking the application
59
- **User Notifications**: Customizable dialogs to prompt users about available updates
60
- **Platform Detection**: Automatically handles macOS (.zip) and Windows (.exe/.nupkg) update formats
61
- **Error Handling**: Comprehensive error handling and logging capabilities
62

63
## Capabilities
64

65
### Auto-Update Management
66

67
Main function to enable auto-updating for Electron applications.
68

69
```typescript { .api }
70
/**
71
 * Enables auto-updating for Electron applications
72
 * @param opts - Configuration options for the updater
73
 */
74
function updateElectronApp(opts: IUpdateElectronAppOptions = {}): void;
75

76
interface IUpdateElectronAppOptions<L = ILogger> {
77
  /** @deprecated Use updateSource instead */
78
  readonly repo?: string;
79
  /** @deprecated Use updateSource instead */
80
  readonly host?: string;
81
  /** Update source configuration */
82
  readonly updateSource?: IUpdateSource;
83
  /** How frequently to check for updates. Defaults to '10 minutes'. Minimum allowed is '5 minutes' */
84
  readonly updateInterval?: string;
85
  /** Custom logger object. Defaults to console */
86
  readonly logger?: L;
87
  /** Whether to notify user when updates are available. Defaults to true */
88
  readonly notifyUser?: boolean;
89
  /** Custom callback for user notification. Only runs if notifyUser is true */
90
  readonly onNotifyUser?: (info: IUpdateInfo) => void;
91
}
92
```
93

94
### User Notification
95

96
Helper function to create customizable user notification dialogs.
97

98
```typescript { .api }
99
/**
100
 * Creates a callback function for customizing user notification dialogs
101
 * @param dialogProps - Customizable text for the dialog
102
 * @returns Callback function for handling update notifications
103
 */
104
function makeUserNotifier(dialogProps?: IUpdateDialogStrings): (info: IUpdateInfo) => void;
105

106
interface IUpdateDialogStrings {
107
  /** Dialog title. Defaults to 'Application Update' */
108
  title?: string;
109
  /** Dialog message. Defaults to 'A new version has been downloaded. Restart the application to apply the updates.' */
110
  detail?: string;
111
  /** Restart button text. Defaults to 'Restart' */
112
  restartButtonText?: string;
113
  /** Later button text. Defaults to 'Later' */
114
  laterButtonText?: string;
115
}
116
```
117

118
### Update Sources
119

120
Configuration for different update source types.
121

122
```typescript { .api }
123
enum UpdateSourceType {
124
  ElectronPublicUpdateService,
125
  StaticStorage
126
}
127

128
interface IElectronUpdateServiceSource {
129
  type: UpdateSourceType.ElectronPublicUpdateService;
130
  /** GitHub repository in format 'owner/repo'. Defaults to package.json repository field */
131
  repo?: string;
132
  /** Base HTTPS URL of update server. Defaults to 'https://update.electronjs.org' */
133
  host?: string;
134
}
135

136
interface IStaticUpdateSource {
137
  type: UpdateSourceType.StaticStorage;
138
  /** Base URL for static storage provider where updates are stored */
139
  baseUrl: string;
140
}
141

142
type IUpdateSource = IElectronUpdateServiceSource | IStaticUpdateSource;
143
```
144

145
### Update Information
146

147
Data structures for update information and logging.
148

149
```typescript { .api }
150
interface IUpdateInfo {
151
  event: Electron.Event;
152
  releaseNotes: string;
153
  releaseName: string;
154
  releaseDate: Date;
155
  updateURL: string;
156
}
157

158
interface ILogger {
159
  log(message: string): void;
160
  info(message: string): void;
161
  error(message: string): void;
162
  warn(message: string): void;
163
}
164
```
165

166
## Platform Support
167

168
- **Supported Platforms**: macOS (darwin), Windows (win32)
169
- **Unsupported Platforms**: Linux and other platforms (will log warning and exit early)
170

171
## Requirements
172

173
- Electron application running on macOS or Windows
174
- For update.electronjs.org: Public GitHub repository with releases published to GitHub Releases
175
- For static storage: Updates published to S3 or similar static file host
176
- Code signing required for macOS applications
177

178
## Update Process
179

180
1. App checks for updates at startup and at configured intervals
181
2. If update found, downloads automatically in background
182
3. When download completes, shows user notification dialog (if enabled)
183
4. User can choose to restart immediately or later
184
5. On restart, update is applied automatically
185

186
## Error Handling
187

188
The library handles various error conditions:
189
- Network connectivity issues during update checks
190
- Invalid repository configurations
191
- Unsupported platforms
192
- File download failures
193
- All errors are logged through the configured logger