Sending Notifications with node-notifier (Mac, Windows, Linux)

Introduction

Notifications provide a great way to engage users of your applications and can be used to provide or solicit feedback. In this tutorial, we will be examining how to send notifications using Node.js and node-notifier.

node-notifier is a library for sending cross-platform native notifications in Node JS.

Creating a Notification with node-notifier

Let's create a directory for our project and initialize a Node project with default settings in it:

$ cd node-native-notifications
$ npm init -y
$ npm install --save node-notifier

Next, in the index.js file, we'll import node-notifier:

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

There are two ways to create and push a simple notification using node-notifier. Passing a string to the notify() function:

notifier.notify('Hello!');

Or, alternatively, you can pass an object, and set attributes such as the title and message:

notifier.notify({
  title: 'Greetings',
  message: 'Hello!'
});

Let's run this code to see the notification in action:

$ node index.js

The notifications are layered over our desktop screen and we can see the two messages we've pushed:

Customizing Notifications

Apart from the title and message options, you can also set an icon to appear, use sound to add a notification sound or use wait to wait for a user action..

The sound and wait are false by default.

Let's add an icon, which can be any image file, as well as a sound to our notification. Additionally, we'll wait for the user to perform an action as well:

const path = require('path');

notifier.notify({
    title: 'Salutations!',
    message: 'Hey there!',
    icon: path.join(__dirname, 'icon.jpg'),
    sound: true,
    wait: true
  },
  function (err, response) {
    console.log(response);
  }
);

In the code above, we are including the path module to help us get the path to our file. We are also passing a callback function to the notify() function and logging the response or user interaction with our notification to the console.

Running the code above, you will get a notification with the image you have chosen as the icon of the notification. A sound of a new notification might also be accompanied with the notification display depending on the operating system OS of your computer and the version.

The notification will look like this:

If you click the button to dismiss the notification, the string dismissed will be logged to your console. If there's no interaction with the notification till it disappears, it displays timeout. If the notification itself is clicked it logs undefined to the console.

Customizing Options for Different Platforms

As stated in the previous section there might be variations in behavior of the notifications sent out due to differences in the reporting systems used by the operating system of the user.

node-notifer tries to use the system with the best user experience but it prefers native solutions. It provides fallbacks for each platform as defined in their decision flow.

However, you can create a customized reporter for each of the reporting systems to have control over the behavior of the notifications you send out in your application. There are five reporters: Notification Center, Windows Toaster, Windows Balloons, Growl, and notify-send.

The wait option does not apply when using Windows Toaster or notify-send reporters as Windows Toasters always wait and notify-send doesn't support the wait option.

The sound option can only used for Notification Center and Windows Toaster reporters. The icon option takes in the absolute path to the image file and does not work for Windows Balloon reporter.

Growl

This is the reporter that is the fallback when other reporters fail or are not available for the OS. It builds on the open-source Growly package and sends messages using the Growl utility to send native notifications.

Add the following to your code to customize the Growl reporter for your application:

const fs = require('fs);
const Growl = require('node-notifier').Growl;
// Or
// const Growl = require('node-notifier/notifiers/growl');
 
let growlNotifier = new Growl({
  name: 'Node'
  host: 'localhost',
  port: 23053
});
 
growlNotifier.notify({
  title: 'Greetings',
  message: 'Hello user!',
  icon: fs.readFileSync(__dirname + '/icon.jpg'),
  wait: false,
  
  // Other growl options like sticky etc.
  sticky: false,
  label: undefined,
  priority: undefined
});

In the code above, we are creating a new Growl instance with a few options set up, such as its name, the host and port it'll be running on.

Next, we call the notify() method with our usual options. Growl introduces us to some more options, which are documented here.

Windows Toaster

This is a reporter specifically for the Windows OS which supports notifications since Windows 8 and newer.

Let's use the Windows Toaster reporter to push a notification:

const WindowsToaster = require('node-notifier').WindowsToaster;
// Or
// const WindowsToaster = require('node-notifier/notifiers/toaster');
 
let windowsToasterNotifier = new WindowsToaster({
  withFallback: true
});
 
windowsToasterNotifier.notify({
    title: "Windows Toaster Notification",
    message: "This is a notification sent from the Windows Toaster Notifier",
    icon:  path.join(__dirname, 'icon.jpg'),
    sound: "SMS",
  },
  function (error, response) {
    console.log(response);
  }
);

Here, we're instantiating a WindowsToaster instance, setting the withFallback argument as true. If this notifier doesn't work, it'll fallback to Growl or Windows Balloons.

Then we are calling the .notify() method with the usual options.

Windows Balloon

This is a reporter specifically for all Windows OS versions below Windows 8. It uses taskbar balloons to show notifications. To customize options for this reporter specifically, you can write your code thus:

const WindowsBalloon = require('node-notifier').WindowsBalloon;
// Or
// const WindowsBallon = require('node-notifier/notifiers/windowsballon');
 
const windowsBalloonNotifier = new WindowsBalloon({
  withFallback: true
});
 
windowsBalloonNotifier.notify({
    title: "Windows Balloon Notification",
    message: "This notification was sent using Windows Balloons.",
    sound: true,
    time: 1000,
    wait: false,
    type: 'warn'
  },
  function (error, response) {
    console.log(response);
  }
);

As usual, we're constructing an instance of the notifier, and passing in our options to the notify() function.

Here, we can specify the time in milliseconds, after which the notification will disappear. We won't wait for the user to perform an action against the notification, so wait is set to false.

Also, we've set the notification type to warn, and sound to true. This will notify the user as a warning. We could've also used info or error depending on what you'd like to convey.

Notification Center

This reporter is for sending notifications for macOS systems. It requires macOS version 10.8 above. For earlier versions, it will use Growl as the fallback. If Growl is not installed, an error is returned in the callback function.

To set up the Notification Center reporter, you can write your code as shown below:

const NotificationCenter = require('node-notifier').NotificationCenter;
// Or
// const NotificationCenter = require('node-notifier/notifiers/notificationcenter');
 
const notificationCenterNotifier = new NotificationCenter({
  withFallback: true
});
 
notificationCenterNotifier.notify({
    title: "Notification Center Notifications",
    subtitle: "For macOS > 10.8",
    message: "This is a notification sent using Notification Center",
    sound: 'Frog',
    icon: path.join(__dirname, 'icon.jpg'),
    contentImage: path.join(__dirname, 'content_image.jpg'),
    open: undefined,
    wait: false,
  },
  function (error, response, metadata) {
    console.log(response, metadata);
  }
);

The sound parameter takes in a bunch of values such as Basso, Blow, Bottle, etc. The default value is Bottle if set to true. Alternatively, you can set a specific sound you'd like.

Notify-send

This reporter is used for customizing notifications to send on a Linux based system. It can be used as shown below:

const NotifySend = require('node-notifier').NotifySend;
// Or
// const NotifySend = require('node-notifier/notifiers/notifysend');
 
let notifySendNotifier = new NotifySend();
 
notifySendNotifier.notify({
  title: 'Notify-send Notification',
  message: 'This notification was sent using the notify-send reporter',
  icon: __dirname + '/icon.jpg',
  wait: true,
  timeout: 5
});

Conclusion

Notifications provide a way for users to interact with your applications and native notifications are those that display on the users desktop as opposed to being displayed in the browser.

In this article, we've covered how to use node-notifier to send notifications to your users.