CLI Update Notifier (CommonJS)

Common errors

• TypeError: Cannot read properties of undefined (reading 'name')

  cause The `pkg` object passed to `updateNotifier` is missing or does not have the required `name` or `version` properties.
  fix Ensure you are passing a valid `pkg` object, typically by reading your `package.json`: `const pkg = require('./package.json'); updateNotifier({pkg});`

• Update notification not appearing on first run or immediately after installing an update.

  cause The library is designed to defer notifications based on `updateCheckInterval` (defaulting to 1 day) and to perform checks asynchronously in a child process to avoid impacting app startup performance. It also specifically waits out the interval before showing any notification, even if an update is available, to avoid annoying users on first install.
  fix For development and testing, temporarily set `updateCheckInterval` to a very low value (e.g., `1000 * 5` for 5 seconds) in the options. Remember to run the application multiple times to trigger the stored notification.

• Notifications not showing up when my CLI is run from a `package.json` script (e.g., `npm run my-cli`).

  cause The `shouldNotifyInNpmScript` option defaults to `false` to prevent unwanted output during automated tasks.
  fix Set `shouldNotifyInNpmScript: true` in the options passed to `updateNotifier`: `updateNotifier({ pkg, shouldNotifyInNpmScript: true }).notify();`

• ERR_REQUIRE_ESM: require() of ES Module [path/to/update-notifier-cjs] not supported.

  cause Attempting to import `update-notifier-cjs` using ES module `import` syntax in an environment that enforces strict module resolution.
  fix This package is strictly CommonJS. Use the `require()` syntax: `const updateNotifier = require('update-notifier-cjs');`. If your project is ESM-only, you might need to consider alternatives or dynamic `import()` if the context allows, though this package is built for CJS.

Warnings

• gotcha Update notifications are not shown on the very first run of a CLI application or if the `updateCheckInterval` has not elapsed. The check runs asynchronously in a detached child process, and results are persisted for subsequent runs. This behavior is designed to be non-intrusive but can be confusing during development/testing.
  Fix: For testing, set a very short `updateCheckInterval` (e.g., `1000 * 5` for 5 seconds) and run your CLI application multiple times, or consult the `example.js` provided by the package for testing strategies. Note that `defer: false` in `notify()` options can force immediate display.
• gotcha The `options.pkg` parameter is mandatory and must contain valid `name` and `version` properties. Failing to provide a correctly structured `pkg` object will result in errors during initialization.
  Fix: Always pass `pkg` derived from your `package.json` file: `const pkg = require('./package.json'); updateNotifier({pkg}).notify();`
• gotcha The `notifier.notify()` method only displays the notification message if the current process is running in a TTY (interactive terminal) environment. Notifications will be silently skipped in non-interactive environments like CI/CD pipelines or automated scripts.
  Fix: This is intended behavior for non-intrusive updates. If you need to log update information regardless of TTY status, manually check `notifier.update` and use `console.log()` if an update is available.
• gotcha By default, update notifications are suppressed when the CLI application is executed as part of an npm script (e.g., `npm run my-script`). This is controlled by the `shouldNotifyInNpmScript` option.
  Fix: To enable notifications in npm scripts, explicitly set `shouldNotifyInNpmScript: true` in the notifier options: `updateNotifier({ pkg, shouldNotifyInNpmScript: true }).notify();`

Install

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

Imports

• updateNotifier
  wrong:

  import { updateNotifier } from 'update-notifier-cjs';

  correct:

  const updateNotifier = require('update-notifier-cjs');

  This package is explicitly CommonJS-only. ES Module `import` syntax will result in a runtime error (e.g., ERR_REQUIRE_ESM) when Node.js attempts to load it.

Quickstart

Demonstrates how to initialize the update notifier and immediately check for and display update notifications for a CLI application using a simple `package.json` object. This example includes settings to facilitate testing.

const updateNotifier = require('update-notifier-cjs');
const pkg = {
  name: 'my-cli-app',
  version: process.env.TEST_APP_VERSION ?? '1.0.0',
  description: 'A simple CLI app'
};

// Simulate an older version to trigger an update notification for testing
// For a real app, use: const pkg = require('./package.json');

// Initialize the notifier with your package info
const notifier = updateNotifier({
  pkg,
  // Set a very short interval for testing purposes
  updateCheckInterval: 1000 * 5, // 5 seconds
  // Allow notification in npm scripts for easier testing
  shouldNotifyInNpmScript: true
});

// Check if an update is available and display a message
if (notifier.update) {
  console.log(`Update available: ${notifier.update.latest}. Current: ${notifier.update.current}`);
  notifier.notify();
} else {
  console.log('No update available or check not yet performed.');
}

// In a real CLI, this would typically run once at startup.