or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-update-notifier

Update notifications for your CLI app

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/update-notifier@7.3.x

To install, run

npx @tessl/cli install tessl/npm-update-notifier@7.3.0

Update Notifier

Update Notifier provides non-intrusive update notifications for CLI applications. It asynchronously checks npm registries for newer versions in background processes without impacting application startup performance, then displays notifications to users when updates are available.

Package Information

Package Name: update-notifier
Package Type: npm
Language: JavaScript (ES Modules)
Installation: npm install update-notifier

Core Imports

import updateNotifier from "update-notifier";

For CommonJS:

const updateNotifier = require("update-notifier");

Basic Usage

import updateNotifier from "update-notifier";
import packageJson from "./package.json" assert { type: "json" };

// Basic usage - checks for updates and displays notification
updateNotifier({ pkg: packageJson }).notify();

// Advanced usage - access update information
const notifier = updateNotifier({ pkg: packageJson });
if (notifier.update) {
  console.log(`Update available: ${notifier.update.latest}`);
}

Capabilities

Factory Function

Creates an UpdateNotifier instance and initiates background update check.

/**
 * Creates UpdateNotifier instance and calls check() automatically
 * @param options - Configuration options
 * @returns UpdateNotifier instance
 */
function updateNotifier(options: UpdateNotifierOptions): UpdateNotifier;

interface UpdateNotifierOptions {
  /** Package information */
  pkg: {
    /** Package name (required) */
    name: string;
    /** Current package version (required) */
    version: string;
  };
  /** Update check interval in milliseconds (default: 86400000 - 1 day) */
  updateCheckInterval?: number;
  /** Allow notifications when running as npm script (default: false) */
  shouldNotifyInNpmScript?: boolean;
  /** NPM dist-tag to check for updates (default: "latest") */
  distTag?: string;
  /** @deprecated Use pkg.name instead */
  packageName?: string;
  /** @deprecated Use pkg.version instead */
  packageVersion?: string;
}

UpdateNotifier Class

Main class for managing update notifications with configurable behavior and persistent storage.

class UpdateNotifier {
  /** Configuration storage instance (undefined if disabled) */
  config?: ConfigStore;
  
  /** Update information when available */
  update?: UpdateInfo;
  
  /** Package name (semi-private, used in tests) */
  _packageName: string;
  
  /** Whether to notify in npm scripts (semi-private, used in tests) */
  _shouldNotifyInNpmScript: boolean;
  
  /**
   * @param options - Configuration options
   * @throws {Error} When pkg.name or pkg.version is missing
   */
  constructor(options: UpdateNotifierOptions);
}

Update Checking

Initiates background check for package updates using detached child processes.

/**
 * Spawns background process to check for updates
 * Respects updateCheckInterval and user preferences
 */
check(): void;

Fetch Update Information

Directly retrieves latest version information from npm registry.

/**
 * Directly fetch update information from npm registry
 * @returns Promise resolving to update information
 */
fetchInfo(): Promise<UpdateInfo>;

interface UpdateInfo {
  /** Latest version available */
  latest: string;
  /** Current installed version */
  current: string;
  /** Update type: "latest" | "major" | "minor" | "patch" | "prerelease" | "build" */
  type: string;
  /** Package name */
  name: string;
}

Notification Display

Shows formatted update notifications with customizable messages and styling.

/**
 * Display update notification to user
 * @param options - Notification options
 * @returns this (for method chaining)
 */
notify(options?: NotifyOptions): UpdateNotifier;

interface NotifyOptions {
  /** Defer notification until process exit (default: true) */
  defer?: boolean;
  /** Custom notification message template */
  message?: string;
  /** Whether package is globally installed (auto-detected) */
  isGlobal?: boolean;
  /** Boxen styling options */
  boxenOptions?: {
    padding?: number;
    margin?: number;
    textAlignment?: string;
    borderColor?: string;
    borderStyle?: string;
  };
}

Message Template System

Template placeholders available for custom notification messages.

// Available template placeholders:
// {packageName} - Package name
// {currentVersion} - Current version  
// {latestVersion} - Latest version
// {updateCommand} - Recommended update command

// Example custom message:
notifier.notify({
  message: "Run `{updateCommand}` to update {packageName} from {currentVersion} to {latestVersion}."
});

Configuration and Environment

User Settings

Users can opt out via configuration file or environment variables:

Config file: ~/.config/configstore/update-notifier-{package-name}.json
Environment variable: NO_UPDATE_NOTIFIER (any value disables)
Command line flag: --no-update-notifier

Automatic Disabling

Update notifications are automatically disabled in:

CI environments (detected via is-in-ci)
Test environments (NODE_ENV=test)
Non-TTY processes (for notify method)
When running during npm script execution (unless shouldNotifyInNpmScript: true)

Config Store Schema

// Configuration stored in ~/.config/configstore/update-notifier-{package-name}.json
interface ConfigStoreData {
  /** User opt-out preference */
  optOut: boolean;
  /** Timestamp of last update check */
  lastUpdateCheck: number;
  /** Cached update information */
  update?: UpdateInfo;
}

Error Handling

Gracefully handles ConfigStore permission errors (EACCES, EPERM)
Shows helpful sudo/permission error messages via boxen
Background check processes have 30-second timeout
Silently fails when offline or in restricted environments
Prevents notifications on first execution (respects updateCheckInterval)

Examples

Basic CLI integration:

import updateNotifier from "update-notifier";
import packageJson from "./package.json" assert { type: "json" };

// Check and notify on app startup
updateNotifier({ pkg: packageJson }).notify();

Custom notification message:

const notifier = updateNotifier({ pkg: packageJson });
notifier.notify({
  message: "🚀 {packageName} v{latestVersion} is available! Run `{updateCommand}` to update.",
  boxenOptions: {
    borderColor: "green",
    borderStyle: "double"
  }
});

Weekly update checks:

const notifier = updateNotifier({
  pkg: packageJson,
  updateCheckInterval: 1000 * 60 * 60 * 24 * 7 // 1 week
});

Programmatic update checking:

const notifier = updateNotifier({ pkg: packageJson });

// Check for updates programmatically
const updateInfo = await notifier.fetchInfo();
if (updateInfo.type !== "latest") {
  console.log(`Update available: ${updateInfo.current} → ${updateInfo.latest} (${updateInfo.type})`);
}

Testing with immediate checks:

import updateNotifier from "update-notifier";

// For testing purposes - bypasses normal interval
const notifier = updateNotifier({
  pkg: { name: "your-package", version: "1.0.0" },
  updateCheckInterval: 0  // Check immediately
});

// Note: Updates won't show on first run (by design)
// Run your app twice to see notifications

Legacy usage (deprecated options):

// Still supported for backwards compatibility
updateNotifier({
  packageName: "your-package",    // @deprecated - use pkg.name
  packageVersion: "1.0.0",        // @deprecated - use pkg.version
  updateCheckInterval: 86400000
}).notify();