Registry / devops / update-notifier-cjs

update-notifier-cjs

JSON →
library5.1.7jsnpmunverified

update-notifier-cjs is a JavaScript library designed to provide non-intrusive update notifications for Command Line Interface (CLI) applications. Currently at version 5.1.7, it is specifically maintained for CommonJS (CJS) environments, providing a direct alternative to `update-notifier` for projects that do not use ES Modules. The library works by asynchronously checking for package updates against the npm registry in a detached child process, ensuring no impact on the CLI tool's startup performance. It persists the check results and displays notifications only after a configurable interval (defaulting to one day), preventing frequent interruptions to the user. This design choice aims to be user-friendly by avoiding immediate notifications on first run or every execution.

devops
npm install update-notifier-cjs
github ↗package ↗
INSTALL
IMPORT
SIG · UPDATE-NOTIFIER-CJ
U
update-notifier-cjs
devopsjavascriptv5.1.7
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

updateNotifier
✓ const updateNotifier = require('update-notifier-cjs');
✗ import { updateNotifier } from '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.

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.
Debug
Known issues
gotchaUpdate 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.
affects: >=1.0.0
gotchaThe `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();`
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
gotchaBy 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();`
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'name')
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.
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`).
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.
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.
Upgrade
Version history
5.1.7latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/ryanblock/update-notifier-cjs ↗
packagehttps://www.npmjs.com/package/update-notifier-cjs ↗
update-notifier-cjs — npm install update-notifier-cjs · libregistry