0
# Update Notifier
1

2
Update Notifier provides non-intrusive update notifications for CLI applications. It asynchronously checks npm registries for newer versions in background processes without impacting application startup performance, then displays notifications to users when updates are available.
3

4
## Package Information
5

6
- **Package Name**: update-notifier
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install update-notifier`
10

11
## Core Imports
12

13
```javascript
14
import updateNotifier from "update-notifier";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const updateNotifier = require("update-notifier");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import updateNotifier from "update-notifier";
27
import packageJson from "./package.json" assert { type: "json" };
28

29
// Basic usage - checks for updates and displays notification
30
updateNotifier({ pkg: packageJson }).notify();
31

32
// Advanced usage - access update information
33
const notifier = updateNotifier({ pkg: packageJson });
34
if (notifier.update) {
35
  console.log(`Update available: ${notifier.update.latest}`);
36
}
37
```
38

39
## Capabilities
40

41
### Factory Function
42

43
Creates an UpdateNotifier instance and initiates background update check.
44

45
```javascript { .api }
46
/**
47
 * Creates UpdateNotifier instance and calls check() automatically
48
 * @param options - Configuration options
49
 * @returns UpdateNotifier instance
50
 */
51
function updateNotifier(options: UpdateNotifierOptions): UpdateNotifier;
52

53
interface UpdateNotifierOptions {
54
  /** Package information */
55
  pkg: {
56
    /** Package name (required) */
57
    name: string;
58
    /** Current package version (required) */
59
    version: string;
60
  };
61
  /** Update check interval in milliseconds (default: 86400000 - 1 day) */
62
  updateCheckInterval?: number;
63
  /** Allow notifications when running as npm script (default: false) */
64
  shouldNotifyInNpmScript?: boolean;
65
  /** NPM dist-tag to check for updates (default: "latest") */
66
  distTag?: string;
67
  /** @deprecated Use pkg.name instead */
68
  packageName?: string;
69
  /** @deprecated Use pkg.version instead */
70
  packageVersion?: string;
71
}
72
```
73

74
### UpdateNotifier Class
75

76
Main class for managing update notifications with configurable behavior and persistent storage.
77

78
```javascript { .api }
79
class UpdateNotifier {
80
  /** Configuration storage instance (undefined if disabled) */
81
  config?: ConfigStore;
82
  
83
  /** Update information when available */
84
  update?: UpdateInfo;
85
  
86
  /** Package name (semi-private, used in tests) */
87
  _packageName: string;
88
  
89
  /** Whether to notify in npm scripts (semi-private, used in tests) */
90
  _shouldNotifyInNpmScript: boolean;
91
  
92
  /**
93
   * @param options - Configuration options
94
   * @throws {Error} When pkg.name or pkg.version is missing
95
   */
96
  constructor(options: UpdateNotifierOptions);
97
}
98
```
99

100
### Update Checking
101

102
Initiates background check for package updates using detached child processes.
103

104
```javascript { .api }
105
/**
106
 * Spawns background process to check for updates
107
 * Respects updateCheckInterval and user preferences
108
 */
109
check(): void;
110
```
111

112
### Fetch Update Information
113

114
Directly retrieves latest version information from npm registry.
115

116
```javascript { .api }
117
/**
118
 * Directly fetch update information from npm registry
119
 * @returns Promise resolving to update information
120
 */
121
fetchInfo(): Promise<UpdateInfo>;
122

123
interface UpdateInfo {
124
  /** Latest version available */
125
  latest: string;
126
  /** Current installed version */
127
  current: string;
128
  /** Update type: "latest" | "major" | "minor" | "patch" | "prerelease" | "build" */
129
  type: string;
130
  /** Package name */
131
  name: string;
132
}
133
```
134

135
### Notification Display
136

137
Shows formatted update notifications with customizable messages and styling.
138

139
```javascript { .api }
140
/**
141
 * Display update notification to user
142
 * @param options - Notification options
143
 * @returns this (for method chaining)
144
 */
145
notify(options?: NotifyOptions): UpdateNotifier;
146

147
interface NotifyOptions {
148
  /** Defer notification until process exit (default: true) */
149
  defer?: boolean;
150
  /** Custom notification message template */
151
  message?: string;
152
  /** Whether package is globally installed (auto-detected) */
153
  isGlobal?: boolean;
154
  /** Boxen styling options */
155
  boxenOptions?: {
156
    padding?: number;
157
    margin?: number;
158
    textAlignment?: string;
159
    borderColor?: string;
160
    borderStyle?: string;
161
  };
162
}
163
```
164

165
### Message Template System
166

167
Template placeholders available for custom notification messages.
168

169
```javascript { .api }
170
// Available template placeholders:
171
// {packageName} - Package name
172
// {currentVersion} - Current version  
173
// {latestVersion} - Latest version
174
// {updateCommand} - Recommended update command
175

176
// Example custom message:
177
notifier.notify({
178
  message: "Run `{updateCommand}` to update {packageName} from {currentVersion} to {latestVersion}."
179
});
180
```
181

182
## Configuration and Environment
183

184
### User Settings
185

186
Users can opt out via configuration file or environment variables:
187

188
- **Config file**: `~/.config/configstore/update-notifier-{package-name}.json`
189
- **Environment variable**: `NO_UPDATE_NOTIFIER` (any value disables)
190
- **Command line flag**: `--no-update-notifier`
191

192
### Automatic Disabling
193

194
Update notifications are automatically disabled in:
195

196
- CI environments (detected via `is-in-ci`)
197
- Test environments (`NODE_ENV=test`)
198
- Non-TTY processes (for notify method)
199
- When running during npm script execution (unless `shouldNotifyInNpmScript: true`)
200

201
### Config Store Schema
202

203
```javascript { .api }
204
// Configuration stored in ~/.config/configstore/update-notifier-{package-name}.json
205
interface ConfigStoreData {
206
  /** User opt-out preference */
207
  optOut: boolean;
208
  /** Timestamp of last update check */
209
  lastUpdateCheck: number;
210
  /** Cached update information */
211
  update?: UpdateInfo;
212
}
213
```
214

215
## Error Handling
216

217
- Gracefully handles ConfigStore permission errors (EACCES, EPERM)
218
- Shows helpful sudo/permission error messages via boxen
219
- Background check processes have 30-second timeout
220
- Silently fails when offline or in restricted environments
221
- Prevents notifications on first execution (respects updateCheckInterval)
222

223
## Examples
224

225
**Basic CLI integration:**
226

227
```javascript
228
import updateNotifier from "update-notifier";
229
import packageJson from "./package.json" assert { type: "json" };
230

231
// Check and notify on app startup
232
updateNotifier({ pkg: packageJson }).notify();
233
```
234

235
**Custom notification message:**
236

237
```javascript
238
const notifier = updateNotifier({ pkg: packageJson });
239
notifier.notify({
240
  message: "🚀 {packageName} v{latestVersion} is available! Run `{updateCommand}` to update.",
241
  boxenOptions: {
242
    borderColor: "green",
243
    borderStyle: "double"
244
  }
245
});
246
```
247

248
**Weekly update checks:**
249

250
```javascript
251
const notifier = updateNotifier({
252
  pkg: packageJson,
253
  updateCheckInterval: 1000 * 60 * 60 * 24 * 7 // 1 week
254
});
255
```
256

257
**Programmatic update checking:**
258

259
```javascript
260
const notifier = updateNotifier({ pkg: packageJson });
261

262
// Check for updates programmatically
263
const updateInfo = await notifier.fetchInfo();
264
if (updateInfo.type !== "latest") {
265
  console.log(`Update available: ${updateInfo.current} → ${updateInfo.latest} (${updateInfo.type})`);
266
}
267
```
268

269
**Testing with immediate checks:**
270

271
```javascript
272
import updateNotifier from "update-notifier";
273

274
// For testing purposes - bypasses normal interval
275
const notifier = updateNotifier({
276
  pkg: { name: "your-package", version: "1.0.0" },
277
  updateCheckInterval: 0  // Check immediately
278
});
279

280
// Note: Updates won't show on first run (by design)
281
// Run your app twice to see notifications
282
```
283

284
**Legacy usage (deprecated options):**
285

286
```javascript
287
// Still supported for backwards compatibility
288
updateNotifier({
289
  packageName: "your-package",    // @deprecated - use pkg.name
290
  packageVersion: "1.0.0",        // @deprecated - use pkg.version
291
  updateCheckInterval: 86400000
292
}).notify();
293
```