CLI Update Notifier

7.3.1 · active · verified Wed Apr 22

update-notifier is a utility package designed to provide non-intrusive update notifications for command-line interface (CLI) applications. Its current stable version is 7.3.1. The package maintains an active release cadence, with several patch and minor updates between major versions, which typically occur every one to two years. A key differentiator is its asynchronous update check mechanism: it performs checks in an unref'ed child process in the background, minimizing impact on the CLI app's startup performance. It also defers initial notifications and subsequent checks based on a configurable `updateCheckInterval`, preventing annoyance and ensuring a smooth user experience. Since v7.0.0, it mandates Node.js 18 or higher, and v6.0.0 transitioned it to a pure ESM package, requiring modern JavaScript module handling. This design philosophy aims to keep CLI tools fresh for users without disrupting their workflow or the developer's application startup speed.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to `import update-notifier` from a CommonJS module (`.js` file without `"type": "module"` in `package.json`, or a `.cjs` file). update-notifier is ESM-only since v6.0.0.

fix Convert your consuming file to an ES module (e.g., rename to `.mjs` or add `"type": "module"` to your `package.json`) and use `import updateNotifier from 'update-notifier';`.
```
ReferenceError: require is not defined
```
cause Using `require()` in an ES module environment (e.g., a file with `import` statements or `"type": "module"` in `package.json`) to load `update-notifier` or any other dependency.

fix Use `import` statements instead of `require()` for all module loading in your ES module. For `update-notifier`, use `import updateNotifier from 'update-notifier';`.
```
npm ERR! EBADENGINE Unsupported engine for update-notifier@7.3.1: wanted: {"node": ">=18"} (current: "v16.x.x")
```
cause Your Node.js version does not meet the minimum requirement specified by `update-notifier`'s `engines` field in its `package.json`.

fix Upgrade your Node.js environment to version 18 or higher using a Node.js version manager like `nvm` or `fnm`.
```
TypeError: Cannot read properties of undefined (reading 'notify')
```
cause This typically occurs if `updateNotifier()` was called without a valid `pkg` option, or if the `pkg` object is missing the `name` or `version` properties, causing `notifier` to be `undefined`.

fix Ensure `updateNotifier()` is called with a `pkg` object that has both `name` and `version` properties, for example: `updateNotifier({pkg: {name: 'my-app', version: '1.0.0'}}).notify();`

Warnings

breaking update-notifier transitioned to a pure ESM package. CommonJS `require()` is no longer supported. This affects how the package is imported and used in projects.
Fix: Migrate your project to use ESM `import` statements and ensure your `package.json` specifies `"type": "module"` or uses `.mjs` file extensions. Refer to the 'read this' link in the v6.0.0 release notes for guidance.
breaking The minimum required Node.js version was increased to 14 for v6.0.0, and further to 18 for v7.0.0. Older Node.js environments will not be able to run `update-notifier` v7.x.
Fix: Upgrade your Node.js environment to version 18 or higher to use `update-notifier` v7.x. If you must use an older Node.js version, you will need to stick to an older `update-notifier` version (e.g., v5.x for Node.js <14).
gotcha The update notification does not appear immediately on the first run of your CLI application. update-notifier respects the `updateCheckInterval` and will only notify after the specified interval has passed, to avoid being intrusive.
Fix: For testing, you can set a very low `updateCheckInterval` (e.g., `1000 * 10` for 10 seconds). Be aware of this behavior during initial implementation and testing cycles.
gotcha Notifications are only displayed when the process is running in a TTY (interactive terminal). They will not be shown in non-interactive environments like CI/CD pipelines or when output is redirected.
Fix: This is intentional behavior to prevent interference in automated scripts. If you need to check for updates programmatically in non-TTY environments, use `notifier.fetchInfo()` and handle the output yourself.
breaking The default update message in v7.0.0 no longer includes Yarn-specific installation commands. If your users rely on the notification providing Yarn instructions, they will no longer see them.
Fix: If supporting Yarn users is critical, you can provide a custom `message` option to `notifier.notify()` to include Yarn-specific instructions.

Install

npm install update-notifier npm
yarn add update-notifier yarn
pnpm add update-notifier pnpm

Imports

updateNotifier
wrong:
```
const updateNotifier = require('update-notifier');
```
correct:
```
import updateNotifier from 'update-notifier';
```
Since v6.0.0, update-notifier is a pure ESM package. CommonJS `require` is no longer supported.
package.json
wrong:
```
import packageJson from './package.json';
```
correct:
```
import packageJson from './package.json' assert {type: 'json'};
```
When importing a local package.json file directly in ESM, Node.js requires the `assert {type: 'json'}` clause for clarity and security. Ensure your Node.js version supports this (Node.js 16.14.0+).
notifier.notify()
wrong:
```
updateNotifier({pkg}).notify({defer: false});
```
correct:
```
notifier.notify();
```
The `defer` option defaults to `true`, which is recommended for non-intrusive notifications. Setting it to `false` might block `process.exit()` for a short period.

Quickstart

This quickstart demonstrates how to initialize `update-notifier`, access update information, and trigger the notification process in a non-blocking way for a CLI application. It sets a short update check interval for easy testing.

import updateNotifier from 'update-notifier';

// In a real CLI, you'd load your package.json dynamically.
// For demonstration, we'll define a basic package object.
const packageDetails = {
    name: 'my-awesome-cli',
    version: '1.0.0'
};

// Initialize the notifier with a short interval for testing purposes
const notifier = updateNotifier({
    pkg: packageDetails,
    updateCheckInterval: 1000 * 10 // Check every 10 seconds for testing
});

// If there's an update, notify the user.
// The notification is typically deferred until the process exits to avoid disrupting the CLI.
notifier.notify({
    defer: true // Default is true, ensures non-blocking behavior
});

// You can also access update information directly
if (notifier.update) {
    console.log(`An update is available for ${notifier.update.name}: ${notifier.update.current} -> ${notifier.update.latest} (${notifier.update.type})`);
} else {
    console.log(`Your CLI (${packageDetails.name} v${packageDetails.version}) is up to date or update check is pending.`);
}

console.log(`\n${packageDetails.name} CLI is now running its main logic...`);

// Simulate a long-running CLI process
setTimeout(() => {
    console.log('CLI finished its operations.');
    // In a real app, ensure process.exit() is called if necessary,
    // but update-notifier works in a detached process, so it won't prevent exit.
}, 3000);

view raw JSON →