{"id":17074,"library":"update-notifier","title":"CLI Update Notifier","description":"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.","status":"active","version":"7.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/yeoman/update-notifier","tags":["javascript","npm","update","updater","notify","notifier","check","checker","cli"],"install":[{"cmd":"npm install update-notifier","lang":"bash","label":"npm"},{"cmd":"yarn add update-notifier","lang":"bash","label":"yarn"},{"cmd":"pnpm add update-notifier","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v6.0.0, update-notifier is a pure ESM package. CommonJS `require` is no longer supported.","wrong":"const updateNotifier = require('update-notifier');","symbol":"updateNotifier","correct":"import updateNotifier from 'update-notifier';"},{"note":"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+).","wrong":"import packageJson from './package.json';","symbol":"package.json","correct":"import packageJson from './package.json' assert {type: 'json'};"},{"note":"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.","wrong":"updateNotifier({pkg}).notify({defer: false});","symbol":"notifier.notify()","correct":"notifier.notify();"}],"quickstart":{"code":"import updateNotifier from 'update-notifier';\n\n// In a real CLI, you'd load your package.json dynamically.\n// For demonstration, we'll define a basic package object.\nconst packageDetails = {\n    name: 'my-awesome-cli',\n    version: '1.0.0'\n};\n\n// Initialize the notifier with a short interval for testing purposes\nconst notifier = updateNotifier({\n    pkg: packageDetails,\n    updateCheckInterval: 1000 * 10 // Check every 10 seconds for testing\n});\n\n// If there's an update, notify the user.\n// The notification is typically deferred until the process exits to avoid disrupting the CLI.\nnotifier.notify({\n    defer: true // Default is true, ensures non-blocking behavior\n});\n\n// You can also access update information directly\nif (notifier.update) {\n    console.log(`An update is available for ${notifier.update.name}: ${notifier.update.current} -> ${notifier.update.latest} (${notifier.update.type})`);\n} else {\n    console.log(`Your CLI (${packageDetails.name} v${packageDetails.version}) is up to date or update check is pending.`);\n}\n\nconsole.log(`\\n${packageDetails.name} CLI is now running its main logic...`);\n\n// Simulate a long-running CLI process\nsetTimeout(() => {\n    console.log('CLI finished its operations.');\n    // In a real app, ensure process.exit() is called if necessary,\n    // but update-notifier works in a detached process, so it won't prevent exit.\n}, 3000);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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).","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If supporting Yarn users is critical, you can provide a custom `message` option to `notifier.notify()` to include Yarn-specific instructions.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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';`.","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use `import` statements instead of `require()` for all module loading in your ES module. For `update-notifier`, use `import updateNotifier from 'update-notifier';`.","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.","error":"ReferenceError: require is not defined"},{"fix":"Upgrade your Node.js environment to version 18 or higher using a Node.js version manager like `nvm` or `fnm`.","cause":"Your Node.js version does not meet the minimum requirement specified by `update-notifier`'s `engines` field in its `package.json`.","error":"npm ERR! EBADENGINE Unsupported engine for update-notifier@7.3.1: wanted: {\"node\": \">=18\"} (current: \"v16.x.x\")"},{"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();`","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`.","error":"TypeError: Cannot read properties of undefined (reading 'notify')"}],"ecosystem":"npm","meta_description":null}