CLI Update Notifier

Common errors

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

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

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

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Always pass an object with `name` and `version` properties as the `pkg` option, typically by importing your application's `package.json` file.
• gotcha 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.
  Fix: If you explicitly want to see update notifications while running within an npm script, set the `shouldNotifyInNpmScript` option to `true`.
• gotcha 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.
  Fix: Update your JSON imports to `import packageJson from './package.json' assert { type: 'json' };` if your project uses ESM and runs on Node.js.

Install

• npm install simple-update-notifier npm
• yarn add simple-update-notifier yarn
• pnpm add simple-update-notifier pnpm

Imports

• updateNotifier
  wrong:

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

  correct:

  import updateNotifier from '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
  wrong:

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

  correct:

  import packageJson from './package.json' assert { type: '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
  wrong:

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

  correct:

  import type { 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.

Quickstart

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();