node-noti

Zero-dependency native desktop notifications for Node.js.

Developed by Yohannes Sisay.

node-noti uses OS-provided notification paths instead of bundling a webview or native binary:

• macOS: osascript and Notification Center
• Windows: built-in PowerShell with .NET tray balloon notifications
• Linux: notify-send from the freedesktop/libnotify desktop notification stack

No runtime dependencies are installed or required.

Install

npm install node-noti

For local global testing from this project folder:

npm link
noti "Hello from noti" --success

Usage

const { notify, success, warning, error, info } = require("node-noti");

await notify({
  title: "Build finished",
  message: "The release package is ready.",
  variant: "success",
  appName: "Release Bot",
  timeout: 4000
});

await success("Deploy completed");
await warning("Disk usage is high");
await error("Backup failed");
await info("Sync started");

Short form:

const { notify } = require("node-noti");

await notify("Upload complete", "All files were synced.");

API

notify(options)

Shows a native notification and resolves with metadata about the backend used.

interface NotifyOptions {
  title: string;
  message?: string;
  variant?: "success" | "warning" | "error" | "info";
  subtitle?: string;
  appName?: string;
  sound?: boolean | string;
  icon?: string;
  timeout?: number;
  urgency?: "low" | "normal" | "critical";
}

isSupported(platform?)

Checks whether the current OS backend is available.

const { isSupported } = require("node-noti");

if (await isSupported()) {
  await notify("Ready", "Notifications are available.");
}

createNotifier(platform?)

Creates the platform-specific notifier service.

CLI

After npm link or global installation, use:

noti "Build completed" --success
noti "Disk usage is high" --warning --title "System"
noti "Backup failed" --error --timeout 7000
noti "Sync started" --info --app-name "Worker"

Supported flags:

• --title <text>
• --app-name <text>
• --timeout <ms>
• --success
• --warning
• --error
• --info

Platform Notes

macOS works on Intel and Apple Silicon because it uses the system osascript executable.

Windows uses built-in Windows PowerShell and System.Windows.Forms.NotifyIcon, which works without external modules. It intentionally avoids optional PowerShell modules such as BurntToast.

Linux desktop notifications are fragmented. This package uses notify-send because it is the standard command-line bridge for freedesktop/libnotify notifications. Minimal server images and stripped desktop environments may not include it.

Variant behavior depends on what the OS backend exposes. Windows maps variants to native tray balloon icons. Linux maps variants to freedesktop urgency and standard icon names unless a custom icon is supplied. macOS Notification Center does not expose success, warning, or error styling through osascript, so the variant is accepted for API consistency without forcing non-native styling.

Security

User-supplied notification text is validated, length-limited, and passed to OS tools without shell interpolation. The Windows backend embeds payload data as base64 JSON inside an encoded PowerShell command to avoid command injection through text fields.

Verification

npm run lint
npm run verify

The package ships compiled JavaScript in dist so consumers do not need TypeScript or any build dependency at install time.