Registry / devops / simple-update-notifier

simple-update-notifier

library2.0.0jsnpmunverified

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`.

devops

npm install simple-update-notifier

github ↗package ↗

INSTALL

IMPORT

SIG · SIMPLE-UPDATE-NOTI

simple-update-notifier

devopsjavascriptv2.0.0

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

✓ import updateNotifier from 'simple-update-notifier';

✗ const updateNotifier = require('simple-update-notifier');

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.

packageJson

✓ import packageJson from './package.json' assert { type: 'json' };

✗ const packageJson = require('./package.json');

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.

NotifierOptions

✓ import type { NotifierOptions } from 'simple-update-notifier';

✗ import { NotifierOptions } from 'simple-update-notifier';

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.

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`.

import updateNotifier from 'simple-update-notifier'; import packageJson from './package.json' assert { type: 'json' }; // In a real CLI application, this would typically be called once at startup. // To demonstrate, we'll create a dummy package.json object if not found. const pkgInfo = packageJson || { name: 'my-cli-app', version: '1.0.0', }; async function main() { console.log('Running CLI app...'); await updateNotifier({ pkg: pkgInfo, updateCheckInterval: 1000 * 60 * 60, // Check hourly for demo purposes shouldNotifyInNpmScript: true, // Allow notifications in npm scripts for testing debug: process.env.DEBUG_UPDATE_NOTIFIER === 'true', // Enable debug logging with env var }); console.log('CLI app finished.'); } main();

Debug

Known issues

breakingVersion 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.

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.

affects: >=2.0.0

gotchaThe `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.

fix

Always pass an object with `name` and `version` properties as the `pkg` option, typically by importing your application's `package.json` file.

affects: >=1.0.0

gotchaUpdate 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.

fix

If you explicitly want to see update notifications while running within an npm script, set the `shouldNotifyInNpmScript` option to `true`.

affects: >=1.0.0

gotchaWhen 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.

fix

Update your JSON imports to `import packageJson from './package.json' assert { type: 'json' };` if your project uses ESM and runs on Node.js.

affects: >=1.0.0

Errors

Common errors & fixes

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

The `pkg` option was not provided or was an empty object, causing the notifier to attempt reading properties from an undefined or incomplete object.

fix

Pass a valid object containing `name` and `version` properties to the `pkg` option, typically derived from your application's `package.json`.

SyntaxError: Unexpected token 'assert'

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.

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');`.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/alexbrazier/simple-update-notifier ↗

packagehttps://www.npmjs.com/package/simple-update-notifier ↗