{"id":17062,"library":"simple-update-notifier","title":"CLI Update Notifier","description":"simple-update-notifier is a lightweight and straightforward utility designed to inform users of command-line interface (CLI) applications about available updates on npm. It works by checking the npm registry for newer versions of a specified package and, if an update is found, prints a non-intrusive notification to the terminal. The library is currently at version 2.0.0, released in June 2023, and maintains a fairly active release cadence with minor and patch updates for dependency management and minor enhancements, and less frequent major releases for breaking changes. A key differentiator is its simplicity and built-in caching mechanism, which prevents excessive API calls to npm by only checking for updates at a configurable interval (defaulting to once a day). It also includes options to control notification behavior in npm scripts and specify different npm `dist-tags`.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/alexbrazier/simple-update-notifier","tags":["javascript","typescript"],"install":[{"cmd":"npm install simple-update-notifier","lang":"bash","label":"npm"},{"cmd":"yarn add simple-update-notifier","lang":"bash","label":"yarn"},{"cmd":"pnpm add simple-update-notifier","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ESM syntax in its examples and is best consumed via `import`. While CJS `require` might work with transpilation or specific Node.js configurations, direct ESM import is recommended.","wrong":"const updateNotifier = require('simple-update-notifier');","symbol":"updateNotifier","correct":"import updateNotifier from 'simple-update-notifier';"},{"note":"When using ESM, importing JSON files requires the `assert { type: 'json' }` clause in Node.js >=16.15. If your project is CommonJS, `require('./package.json')` is the correct approach.","wrong":"const packageJson = require('./package.json');","symbol":"packageJson","correct":"import packageJson from './package.json' assert { type: 'json' };"},{"note":"NotifierOptions is a TypeScript type definition and should be imported using `import type` to avoid bundling it at runtime, especially important for bundlers that might incorrectly include type-only imports.","wrong":"import { NotifierOptions } from 'simple-update-notifier';","symbol":"NotifierOptions","correct":"import type { NotifierOptions } from 'simple-update-notifier';"}],"quickstart":{"code":"import updateNotifier from 'simple-update-notifier';\nimport packageJson from './package.json' assert { type: 'json' };\n\n// In a real CLI application, this would typically be called once at startup.\n// To demonstrate, we'll create a dummy package.json object if not found.\nconst pkgInfo = packageJson || {\n  name: 'my-cli-app',\n  version: '1.0.0',\n};\n\nasync function main() {\n  console.log('Running CLI app...');\n  await updateNotifier({\n    pkg: pkgInfo,\n    updateCheckInterval: 1000 * 60 * 60, // Check hourly for demo purposes\n    shouldNotifyInNpmScript: true, // Allow notifications in npm scripts for testing\n    debug: process.env.DEBUG_UPDATE_NOTIFIER === 'true', // Enable debug logging with env var\n  });\n  console.log('CLI app finished.');\n}\n\nmain();","lang":"typescript","description":"This quickstart demonstrates how to integrate `simple-update-notifier` into a CLI application. It shows importing the notifier and passing a `pkg` object (typically from `package.json`) along with optional configuration like `updateCheckInterval` and `shouldNotifyInNpmScript`."},"warnings":[{"fix":"Ensure your project's Node.js environment is version 10 or higher. If you are on an older Node.js version, you must either upgrade Node.js or remain on `simple-update-notifier` v1.x.","message":"Version 2.0.0 introduced a breaking change by raising the minimum required Node.js version. This was done to bump the `semver` dependency and avoid potential audit errors for users of the library.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always pass an object with `name` and `version` properties as the `pkg` option, typically by importing your application's `package.json` file.","message":"The `pkg` option is mandatory and must contain `name` and `version` properties. Forgetting to pass the `package.json` data will prevent the notifier from functioning correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you explicitly want to see update notifications while running within an npm script, set the `shouldNotifyInNpmScript` option to `true`.","message":"Update notifications are disabled by default when running in an npm script context (e.g., `npm run my-script`). This prevents noisy output during build processes or CI/CD pipelines.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your JSON imports to `import packageJson from './package.json' assert { type: 'json' };` if your project uses ESM and runs on Node.js.","message":"When using ESM in Node.js, directly `import`ing `package.json` requires the `assert { type: 'json' }` clause. This is a Node.js-specific syntax for JSON modules.","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":"Pass a valid object containing `name` and `version` properties to the `pkg` option, typically derived from your application's `package.json`.","cause":"The `pkg` option was not provided or was an empty object, causing the notifier to attempt reading properties from an undefined or incomplete object.","error":"TypeError: Cannot read properties of undefined (reading 'name')"},{"fix":"Upgrade your Node.js environment to version 16.15 or higher. If using a bundler, ensure it's configured to handle JSON modules with import assertions. Alternatively, if your project is CommonJS, use `const packageJson = require('./package.json');`.","cause":"You are using the `import ... assert { type: 'json' }` syntax for JSON modules but your Node.js version is too old (pre-16.15) or your environment does not support it, or your bundler isn't configured for it.","error":"SyntaxError: Unexpected token 'assert'"}],"ecosystem":"npm","meta_description":null}