@santana-org/update-notifier

📦 Install

npm install @santana-org/update-notifier
pnpm add @santana-org/update-notifier

🚀 Quickstart

import { createUpdateNotifier } from "@santana-org/update-notifier"
import { createRequire } from "node:module"

const pkg = createRequire(import.meta.url)("./package.json")

const notifier = createUpdateNotifier({
  packageName: pkg.name,
  currentVersion: pkg.version,
})

// kick off the background check at startup (non-blocking)
notifier.check()

// ... run your CLI ...

// at the very end, print the notice if an update is available
await notifier.notify()

Output when outdated:

  Update available!  1.0.0 → 1.2.3
  Run npm i -g your-cli to update

📖 API

createUpdateNotifier(options)

Returns an UpdateNotifier object with two methods.

| Option | Type | Default | Description | |---|---|---|---| | packageName | string | — | npm package name to check | | currentVersion | string | — | Currently installed version | | ttlMs | number | 86400000 | Cache TTL in milliseconds (default 24 h) | | registry | string | npm registry | Custom registry URL | | colorsEnabled | boolean | auto | Force or disable colorized output |

notifier.check() — fires the background registry request. Call this as early as possible so the network round-trip overlaps with your CLI work. Non-blocking.

notifier.notify(stream?) — awaits the pending check and writes the update notice to stream (default process.stderr) if a newer version is available. Safe to call even if check() was never called.

checkUpdate(options)

Lower-level one-shot check that returns an UpdateInfo object directly:

const info = await checkUpdate({ packageName: "my-cli", currentVersion: "1.0.0" })

if (info.isOutdated) {
  console.log(info.message)
  // info.current → "1.0.0"
  // info.latest  → "1.2.3"
}

compareVersions(a, b) / isNewer(a, b)

Semver utilities:

compareVersions("1.2.3", "1.2.0") // 1
isNewer("1.2.3", "1.2.0")         // true

🧩 Recipes

Disable in CI

const notifier = createUpdateNotifier({ packageName, currentVersion })

if (!process.env.CI) notifier.check()

// ...

await notifier.notify()

Custom registry

const notifier = createUpdateNotifier({
  packageName: "@myorg/cli",
  currentVersion: "2.0.0",
  registry: "https://npm.myorg.com",
})

🏗️ Design decisions

• Non-blocking. The registry fetch runs in the background — it never delays the user's command.
• Cached for 24 h. Results are stored in ~/.cache/santana-update-notifier/ so only one check per day hits the network.
• Silent on failure. Network errors, registry timeouts, and cache write failures are all swallowed — the CLI keeps running.
• ESM-first. CJS interop included, but the package is written for modern runtimes.

📄 License

MIT © santana-org — contributions are welcome, see CONTRIBUTING.