{"id":17071,"library":"update-notifier-cjs","title":"CLI Update Notifier (CommonJS)","description":"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.","status":"active","version":"5.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/ryanblock/update-notifier-cjs","tags":["javascript","npm","update","updater","notify","notifier","check","checker","cli"],"install":[{"cmd":"npm install update-notifier-cjs","lang":"bash","label":"npm"},{"cmd":"yarn add update-notifier-cjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add update-notifier-cjs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { updateNotifier } from 'update-notifier-cjs';","symbol":"updateNotifier","correct":"const updateNotifier = require('update-notifier-cjs');"}],"quickstart":{"code":"const updateNotifier = require('update-notifier-cjs');\nconst pkg = {\n  name: 'my-cli-app',\n  version: process.env.TEST_APP_VERSION ?? '1.0.0',\n  description: 'A simple CLI app'\n};\n\n// Simulate an older version to trigger an update notification for testing\n// For a real app, use: const pkg = require('./package.json');\n\n// Initialize the notifier with your package info\nconst notifier = updateNotifier({\n  pkg,\n  // Set a very short interval for testing purposes\n  updateCheckInterval: 1000 * 5, // 5 seconds\n  // Allow notification in npm scripts for easier testing\n  shouldNotifyInNpmScript: true\n});\n\n// Check if an update is available and display a message\nif (notifier.update) {\n  console.log(`Update available: ${notifier.update.latest}. Current: ${notifier.update.current}`);\n  notifier.notify();\n} else {\n  console.log('No update available or check not yet performed.');\n}\n\n// In a real CLI, this would typically run once at startup.","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always pass `pkg` derived from your `package.json` file: `const pkg = require('./package.json'); updateNotifier({pkg}).notify();`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To enable notifications in npm scripts, explicitly set `shouldNotifyInNpmScript: true` in the notifier options: `updateNotifier({ pkg, shouldNotifyInNpmScript: true }).notify();`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are passing a valid `pkg` object, typically by reading your `package.json`: `const pkg = require('./package.json'); updateNotifier({pkg});`","cause":"The `pkg` object passed to `updateNotifier` is missing or does not have the required `name` or `version` properties.","error":"TypeError: Cannot read properties of undefined (reading 'name')"},{"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.","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.","error":"Update notification not appearing on first run or immediately after installing an update."},{"fix":"Set `shouldNotifyInNpmScript: true` in the options passed to `updateNotifier`: `updateNotifier({ pkg, shouldNotifyInNpmScript: true }).notify();`","cause":"The `shouldNotifyInNpmScript` option defaults to `false` to prevent unwanted output during automated tasks.","error":"Notifications not showing up when my CLI is run from a `package.json` script (e.g., `npm run my-cli`)."},{"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.","cause":"Attempting to import `update-notifier-cjs` using ES module `import` syntax in an environment that enforces strict module resolution.","error":"ERR_REQUIRE_ESM: require() of ES Module [path/to/update-notifier-cjs] not supported."}],"ecosystem":"npm","meta_description":null}