DOCSEARCHbyAlgolia
Submit Docs

node-notifier

repository·master·Indexed 26 days ago

https://github.com/mikaelbr/node-notifier

A Node.js module for sending cross-platform native desktop notifications. It supports macOS (Notification Center), Windows (Toasters and Balloons), Linux (notify-osd/libnotify), and Growl as a fallback. Version 10.0.1 provides a cross-platform wrapper via notifier.notify() as well as direct access to platform-specific reporters like NotificationCenter, WindowsToaster, WindowsBalloon, and NotifySend.

Tokens
4.4K
Snippets
12
Records
20
Agent score
41%

What's inside node-notifier

  1. System Requirements for node-notifier

    master

    The library uses different native reporters based on your operating system:

    • macOS: Requires macOS >= 10.8 for native notifications. Earlier versions use Growl.
    • Linux: Requires notify-osd or libnotify-bin to be installed (usually default on Ubuntu).
    • Windows: Requires Windows >= 8 for Toasters. For Windows < 8, it uses taskbar balloons. Growl is a fallback and takes precedence over Windows balloons.
    • General Fallback: Growl is used if the above requirements are not met.

  2. Advanced Cross-Platform Usage

    master

    For more control, use an options object with notifier.notify(). You can provide a title, message, icon path, sound toggle, and a wait flag.

    When wait: true is used, the callback function is executed when the user interacts with the notification. Note that wait does not apply to Windows Toasters or notify-send (Linux).

    Available events:

    • click: Triggers if wait: true and the user clicks the notification.
    • timeout: Triggers if wait: true and the notification closes automatically.
    const notifier = require('node-notifier');
const path = require('path');

notifier.notify(
  {
    title: 'My awesome title',
    message: 'Hello from node, Mr. User!',
    icon: path.join(__dirname, 'coulson.jpg'), // Absolute path (doesn't work on balloons)
    sound: true, // Only Notification Center or Windows Toasters
    wait: true // Wait with callback, until user action is taken against notification
  },
  function (err, response, metadata) {
    // Response is response from notification
    // Metadata contains activationType, activationAt, deliveredAt
  }
);

notifier.on('click', function (notifierObject, options, event) {
  // Triggers if `wait: true` and user clicks notification
});

notifier.on('timeout', function (notifierObject, options) {
  // Triggers if `wait: true` and notification closes
});

  4. Fix node-notifier loading in Electron (asar)

    master

    When packaging an Electron app as an asar, node-notifier will fail to load because binaries cannot be executed from within an asar archive. To resolve this, you must unpack the vendor/ folder of node-notifier during the packaging process.

    If using the asar CLI directly, use the --unpack flag:

    asar pack . app.asar --unpack "./node_modules/node-notifier/vendor/**"

    If using electron-builder, add the asarUnpack option to your build configuration in package.json:

    "build": {
  "asarUnpack": [
    "./node_modules/node-notifier/**/*"
  ]
}

  7. Troubleshoot macOS custom icons

    master

    On macOS, notifications will always show the icon of the parent application initiating the notification. Since node-notifier uses terminal-notifier as the initiator, you will see the Terminal icon even if you define a custom icon in your configuration.

    To display a custom icon instead of the Terminal icon, you must fork terminal-notifier and build your own version with your desired icon embedded.

  9. Configure Webpack to support node-notifier

    master

    When using node-notifier with Webpack, you must ensure that __filename and __dirname are available. node-notifier relies on relative file paths to load notification binaries, and Webpack's default compilation suppresses these directories, causing errors on certain platforms.

    Add the following configuration to your webpack.config.js:

    node: {
  __filename: true,
  __dirname: true
}

  10. Quick Usage for native notifications

    master

    You can send a simple native notification on macOS, Windows, or Linux by passing either a string or an options object to notifier.notify().

    const notifier = require('node-notifier');

// Send as a simple string
notifier.notify('Message');

// Send with a title and message object
notifier.notify({
  title: 'My notification',
  message: 'Hello, there!'
});

  11. Access reporters via the main module

    master

    You can also access the individual reporters through the main node-notifier instance. Note that this method may take longer to require as it loads the reporter modules.

    // NOTE: Technically, this takes longer to require
const nn = require('node-notifier');

new nn.NotificationCenter(options).notify();
new nn.NotifySend(options).notify();
new nn.WindowsToaster(options).notify(options);
new nn.WindowsBalloon(options).notify(options);
new nn.Growl(options).notify(options);

  12. Use Growl for notifications

    master

    The Growl class is used for Growl notifications. It requires the growly project to be available.

    const Growl = require('node-notifier').Growl;

var notifier = new Growl({
  name: 'Growl Name Used', // Defaults as 'Node'
  host: 'localhost',
  port: 23053
});

notifier.notify({
  title: 'Foo',
  message: 'Hello World',
  icon: fs.readFileSync(__dirname + '/coulson.jpg'),
  wait: false, // Wait for User Action against Notification
  sticky: false,
  label: undefined,
  priority: undefined
});