Notification

Create native OS desktop notifications from the main process on macOS and Linux.

Create native OS desktop notifications. Notification extends Node’s EventEmitter, so the full listener API (on/once/addListener/…) matches Electron’s contract. It is a main-process module backed by Cocoa’s NSUserNotification on macOS and libnotify on Linux. Like Electron, instantiating a notification does not show it - you call show() for that.

Process: Main

Methods

notification.show()

show(): void

Displays the notification and synchronously emits the show event. As in Electron, constructing a Notification does not display anything; you must call show(). Calling it again re-presents the notification.

import { Notification } from 'bunmaska';

const n = new Notification({
  title: 'Build finished',
  body: 'Your bundle is ready.',
});

n.show();

notification.close()

close(): void

Dismisses the notification if it is currently showing. Idempotent - calling it when nothing is shown (or calling it twice) is a no-op and will not throw.

import { Notification } from 'bunmaska';

const n = new Notification({ title: 'Heads up', body: 'Auto-dismissing in 5s.' });
n.show();

setTimeout(() => n.close(), 5000);

Events

Event: ‘show’

Emitted synchronously when show() is called. As in Electron, this can fire multiple times since show() can be called repeatedly.

import { Notification } from 'bunmaska';

const n = new Notification({ title: 'Hello', body: 'World' });
n.on('show', () => console.log('notification shown'));
n.show();

Event: ‘close’

Emitted when the OS reports that the notification was dismissed or closed.

Honest platform caveat:

  • Linux - fully wired. The NotifyNotification::closed signal from the notification daemon is connected to this event, so close fires when the user (or the system) dismisses the notification.
  • macOS - best-effort only. The un-bundled NSUserNotification path has no delegate to report a real close, so the handle’s onClosed is a no-op; do not rely on close firing on macOS in the current version.
import { Notification } from 'bunmaska';

const n = new Notification({ title: 'Job', body: 'Running…' });
n.on('close', () => console.log('notification closed by the user/OS'));
n.show();

Properties

All four properties are plain mutable instance fields set from the constructor options (defaulting to '' for strings and false for silent). Note that, unlike Electron, mutating a property after show() does not update an already-presented notification - set them before calling show().

notification.title

title: string

The bold first line of the notification. Defaults to ''.

notification.body

body: string

The body text shown under the title. Defaults to ''.

notification.subtitle macOS

subtitle: string

A secondary line shown under the title. Wired only on macOS (mapped to NSUserNotification’s setSubtitle:); the field exists on every platform but is ignored by the Linux backend. Defaults to ''.

notification.silent

silent: boolean

Whether to suppress the notification sound. Works on both platforms. Defaults to false. (On macOS, silent: false opts into the default sound name, since NSUserNotification is otherwise silent.)

import { Notification } from 'bunmaska';

const n = new Notification();
n.title = 'Deploy complete';
n.subtitle = 'production'; // macOS only
n.body = 'All services are green.';
n.silent = true;
n.show();

Static methods

Notification.isSupported()

static isSupported(): boolean

Returns whether the host platform can actually deliver notifications. This is the honest answer, not a hardcoded true:

  • Linux - true once libnotify is loaded and notify_init succeeded.
  • macOS - false when run un-bundled, because the default notification center is nil without an app bundle. Reliable macOS delivery needs packaging (a follow-up).

On any other platform, the underlying backend lookup throws UnsupportedPlatformError (Bunmaska targets macOS and Linux only - no Windows).

import { Notification } from 'bunmaska';

if (Notification.isSupported()) {
  new Notification({ title: 'Ready', body: 'Notifications are available.' }).show();
} else {
  console.log('Desktop notifications are not available on this host.');
}

Not in Bunmaska (yet)

Bunmaska implements a deliberately small, honest subset. The following Electron Notification members are not present in the current source:

  • User-interaction events - click, reply, and action are deferred in v1. They require OS delegate/action wiring (an NSUserNotificationCenterDelegate on macOS, action capabilities on Linux) that is not yet implemented, so they are intentionally not advertised. The failed event is also not emitted.
  • Constructor options - only title, body, subtitle, and silent are supported. icon, hasReply, replyPlaceholder, sound, urgency, timeoutType, actions, closeButtonText, id, groupId, groupTitle, and toastXml are not implemented.
  • Properties - correspondingly, there are no icon, hasReply, replyPlaceholder, sound, urgency, timeoutType, actions, closeButtonText, id, groupId, or groupTitle properties.
  • Static methods - Notification.getHistory(), Notification.remove(), Notification.removeAll(), and Notification.removeGroup() (all macOS in Electron) are not implemented. Notification.handleActivation() is Windows-only in Electron and out of scope here.
  • Windows - not a target platform at all.