Home
Softono
node-toasted-notifier

node-toasted-notifier

Open source MIT JavaScript
GitHub
26
Stars
3
Forks
11
Issues
1
Watchers
7 months
Last Commit
Terminal Emulators Push Notifications

About node-toasted-notifier

A revised fork of node-notifier; NodeJS package for pushing notifications to MacOS, Linux, and Windows.

Platforms

Web Self-hosted Linux Windows macOS

Languages

JavaScript

Links

Source Code
a
Published by
aetherinox
Visit View Profile

README.md

View on GitHub

♾️ Toasted Notifier ♾️


Toasted Notifier is a forked version of node-notifier which has been updated with various changes. It allows for you to display push notifications within your application for Windows, Linux, and macOS.


This library is packaged with ntfy-desktop


Version Build Status Downloads Size Last Commit








About

Toasted Notifier allows you to send cross platform native notifications using Node.js, and works well with Electron.


This node package toasted-notifier contains a combination of supported notification vendors, which allows a user on any operating system to use this package in their application. The following list shows all of the notification vendors this package supports, which operating system it is for, and the filename for where the code belonging to that notification system can be found in this package:

Notification API Operating System File View Docs
WindowToaster Windows 8, 10, and 11 notifiers\toaster.js view
WindowsBalloon Windows XP / 7 notifiers\balloon.js view
NotifySend Linux notifiers\notifysend.js view
NotificationCenter macOS / OS X notifiers\notificationcenter.js view
Growl macOS / OS X, Windows notifiers\growl.js view


When you include toasted-notifier in your node project, the API will automatically detect what operating system you are running your application on. Depending on the operating system, Toasted Notifier will call the correct notification package that it will use to show your coded notifications. The following outlines how the package acts and what it takes into consideration:

  • NotificationCenter: macOS
    • This package will be used if you are running on macOS >= 10.8 or newer.
    • If running on an older version of macOS, Growl will be used instead.
    • Messages sent using terminal-notify
  • NotifySend: Linux / Unix
    • Notifications will be shown using notify-osd or libnotify-bin; which must be installed on your Linux system.
    • Ubuntu should have one of these packages by default
  • WindowToaster: Microsoft Windows 8, 9, 10, 11+
  • WindowsBalloon: Windows XP, 7
  • Growl: macOS, Windows
    • This notification system is called if none of the requirements for the other notification vendors are met


What is ntfy-toast

This node package toasted-notifier utilizes a custom built library known as ntfy-toast in order to show notifications on a user's system.

When you add this node package to your application and send a notification, data will be sent from this node package toasted-notifier over to ntfy-toast with the details about what the notification should say to the user. Think of toasted-notifier as a wrapper that handles the communication between your app, and the notification app itself. toasted-notifier will do all of the talking between your app and ntfy-toast each time a notification is triggered to be sent.

ntfy-toast is based on SnoreToast, but has been updated with numerous new features.



Features

  • Notification support for Windows XP - 11, Linux, and MacOS.
  • Windows custom appID support for branding
  • Persistent notifications keep a message on-screen until the user dismisses it
  • No change in code if coming over from node-notifier
  • Customize sounds and icons



Install

Simply install it using:

npm install --save toasted-notifier



Usage

Information and examples for implementing notifications:


[!NOTE] We have provided numerous written examples that you can view by going to the example folder of our repo:


Cross-Platform Advanced Usage

If you wish to ensure that your node application supports all operating systems, (Windows, Linux, Mac), you can use the following javascript as an example to build your notifications around:

const toasted = require('toasted-notifier');
const path = require('path');

toasted.notify(
    {
        title: 'Notification Title',
        message: 'This is a message',
        icon: path.join(__dirname, 'example_1.png'),    // Absolute path (doesn't work on balloons)
        sound: true,                                    // Only Notification Center or Windows Toasters
        wait: true                                      // Wait on callback until user interacts, does not apply to Windows Toasters as they always wait or notify-send as it does not support the wait option
    },
    ( error, response, metadata ) =>
    {
        // Response is response from notification
        // Metadata contains activationType, activationAt, deliveredAt
    }
);

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

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


Fine-grained Control

If you want super fine-grained control for each vendor; you can call them individually. This allows you to tune specific options for the different vendors.

See below for documentation on each notification vendor.

/*
    create option structure
*/

const options =
{
    withFallback: true,       // try Windows Toast and Growl first?
    customPath: undefined     // relative / absolute path if you want to use your own fork
};

/*
    send notification to users running macOS 10.8 or newer
*/

const NotificationCenter = require('toasted-notifier/notifiers/notificationcenter');
new NotificationCenter(options).notify();

/*
    send notification to users running Linux
*/

const NotifySend = require('toasted-notifier/notifiers/notifysend');
new NotifySend(options).notify();

/*
    send notification to users running Windows 8, 10, 11
*/

const WindowsToaster = require('toasted-notifier/notifiers/toaster');
new WindowsToaster(options).notify();

/*
    send notification to users running Windows XP or 7
*/

const WindowsBalloon = require('toasted-notifier/notifiers/balloon');
new WindowsBalloon(options).notify();

/*
    send notification to users running Windows or macOS
    this is the fallback used if the above notification vendors aren't available.
*/

const Growl = require('toasted-notifier/notifiers/growl');
new Growl(options).notify();


If you're using several vendors:

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

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


Specific Vendor Documentation

To see information about each specific vendor and operating system, select one below:

The following different types of notifications are listed below:

Notification API Operating System File View Docs
WindowToaster Windows 8, 10, and 11 notifiers\toaster.js view
WindowsBalloon Windows XP / 7 notifiers\balloon.js view
NotifySend Linux notifiers\notifysend.js view
NotificationCenter macOS / OS X notifiers\notificationcenter.js view
Growl macOS / OS X notifiers\growl.js view


NotificationCenter

  • A Node.js wrapper for terminal-notify (with fallback).
  • Code available at: node_modules\toasted-notifier\notifiers\notificationcenter.js
  • Requires macOS version 10.8 or higher; otherwise the fallback is Growl. If growl is not installed, an error will be returned in the callback.


Since toasted-notifier wraps around terminal-notifier, you can do anything terminal-notifier can by passing properties to the method.

  • if terminal-notifier says -message, you can do {message: 'Foo'}
  • if terminal-notifier says -list ALL, you can do {list: 'ALL'}


Notification is the primary focus of this module, so listing and activating do work, but they aren't documented.


const NotificationCenter = require('toasted-notifier').NotificationCenter;

const toasted = new NotificationCenter(
{
    withFallback: false,        // Use Growl Fallback if <= 10.8
    customPath: undefined       // Relative/Absolute path to binary if you want to use your own fork of terminal-notifier
});

toasted.notify(
    {
        title: undefined,
        subtitle: undefined,
        message: undefined,
        sound: false,               // Case Sensitive string for location of sound file, or use one of macOS' native sounds (see below)
        icon: 'Terminal Icon',      // Absolute Path to Triggering Icon
        contentImage: undefined,    // Absolute Path to Attached Image (Content Image)
        open: undefined,            // URL to open on Click
        wait: false,                // Wait for User Action against Notification or times out. Same as timeout = 5 seconds

        // New in latest version. See `example/macInput.js` for usage
        timeout: 5,                 // Takes precedence over wait if both are defined.
        closeLabel: undefined,      // String. Label for cancel button
        actions: undefined,         // String | Array<String>. Action label or list of labels in case of dropdown
        dropdownLabel: undefined,   // String. Label to be used if multiple actions
        reply: false                // Boolean. If notification should take input. Value passed as third argument in callback and event emitter.
    },
    ( error, response, metadata ) =>
    {
        console.log( response, metadata );
    }
);


[!NOTE] The wait option is shorthand for timeout: 5. This just sets a timeout for 5 seconds. It does not make the notification stick until the user interacts with it.

macOS Notifications: icon, contentImage, and all forms of reply/actions require macOS 10.9.


Default timeout is 10 to ensure that the application closes properly. To remove the timeout and have notifications instantly close (does not support actions), set timeout: false. If you are using an action: declaration; it is recommended to set the timeout to a high value to ensure the user has time to respond to the notification.

[!NOTE] Exception: If reply: true is defined, set timeout to a high value, or to nothing at all.


Sounds

When specifying a sound, you have the following options:

  • Basso
  • Blow
  • Bottle
  • Frog
  • Funk
  • Glass
  • Hero
  • Morse
  • Ping
  • Pop
  • Purr
  • Sosumi
  • Submarine
  • Tink


If sound: true, Bottle is the default sound.



See Also:



Custom Path

customPath takes a string which can be either a relative or absolute path to the binary of your fork/custom version of terminal-notifier.

Example: ./vendor/mac.noindex/terminal-notifier.app/Contents/MacOS/terminal-notifier


Spotlight

terminal-notifier.app is located in the mac.noindex folder to prevent Spotlight from indexing the app. You can find it in:

  • toasted-notifier\vendor\mac.noindex\terminal-notifier.app


WindowsToaster

  • A Node.js wrapper for Windows 8, 10, and 11 notifications.
  • Code available at: node_modules\toasted-notifier\notifiers\toaster.js


Note: There are limitations for images in native Windows 8 notifications:

  • Image must be a PNG image
  • Image must be smaller than 1024×1024px
  • Image must be less than 200kb
  • Image must be specified using an absolute path

These limitations are due to the Toast notification system. A good tip is to use something like path.join or path.delimiter to keep your paths cross-platform.


Notifications Not Working

If you do not see notifications from Toasted-Notifier, click windows Start and locate:


Locate NtfyToast, or your customPath / appID program in the list.


[!NOTE] ntfy-toast is the library used by this node package toasted-notifier for Windows notifications



Enable both permissions for banner and sound:

Windows 10 Fall Creators Update (Version 1709):

This node package utilizes ntfy-toast to display native Windows notifications.


By default when a notification is displayed, the application name at the top of the popup will be NtfyToast. The app has an app id which is fed into Toasted-Notifier which is how the notification system knows what application name to show at the top of each notification. The app id is built into each application.


With the Fall Creators Update, Notifications on Windows 10 will only work as expected if a valid appID is specified. The appID must be exactly the same value that was registered during the installation of the app.


If you wish to have an alternative program name show at the top of each notification, you will need to feed your own app id into the code that calls your notification toasts.


For a in-depth write-up on how to get the app id for your custom program, read the section appID support.


You can attempt to quickly find the appID for an application by opening PowerShell and executing the command:

get-StartApps | Where-Object {$_.Name -like '*YourAppName*'}


In our example, we can run

get-StartApps | Where-Object {$_.Name -like '*Ntfytoast*'}


Which returns the following:

Name          AppID
----          -----
ntfytoast     com.ntfytoast.id


You can also find the ID of your App by searching the registry for the appID you specified at installation of your app. For example: If you use the squirrel framework, your appID would be com.squirrel.your.app.


Once you have found the custom app id you wish to use for notifications; you can provide it when calling a notification, such as with the example below, in which we use com.ntfytoast.id:


const WindowsToaster = require('toasted-notifier').WindowsToaster;

const toasted = new WindowsToaster(
{
    withFallback: false,            // Fallback to Growl or Balloons
    customPath: undefined           // Relative/Absolute path if you want to use your fork of SnoreToast.exe
});

toasted.notify(
    {
        title: undefined,           // String           | Required
        message: undefined,         // String           | Required if remove is not defined
        icon: undefined,            // String           | Absolute path to Icon
        sound: false,               // Bool or String   | (as defined by http://msdn.microsoft.com/en-us/library/windows/apps/hh761492.aspx)
        id: undefined,              // Number           | ID to use for closing notification.
        appID: 'com.ntfytoast.id',  // String           | App.ID and app Name. Defaults to no value, causing SnoreToast text to be visible.
        remove: undefined,          // Number           | Refer to previously created notification to close.
        install: undefined          // String           | <path, application, app id> |  Creates a shortcut <path> in the start menu which point to the executable <application>, appID used for the notifications.
    },
    ( error, response ) =>
    {
        console.log( response );
    }
);


As stated before, there is a very in-depth write-up on how to set up your custom application and how to obtain the app id by reading the section appID support.


Growl

  • A Node.js wrapper for MacOS, also used as a fallback.
  • Code available at: node_modules\toasted-notifier\notifiers\growl.js
  • View Growl Github Repo


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

const toasted = new Growl({
    name: 'Growl Name Used', // Defaults to 'Node'
    host: 'localhost',
    port: 23053
});

toasted.notify(
{
    title: 'Foo',
    message: 'My Message',
    icon: fs.readFileSync(__dirname + '/example_1.png'),
    wait: true,                     // whether or not to sticky the notification (defaults to false.)
    label: undefined,               // type of notification to use (defaults to the first registered notification type.)
    priority: undefined             // the priority of the notification from lowest (-2) to highest (2).
});


WindowsBalloon

  • A Node.js wrapper for earlier versions of Windows such as Windows XP / 7.
  • Code available at: node_modules\toasted-notifier\notifiers\balloon.js
  • Uses the 3rd party library Notifu, located at: node_modules\toasted-notifier\vendor\notifu 


const WindowsBalloon = require('toasted-notifier').WindowsBalloon;

const toasted = new WindowsBalloon(
{
    withFallback: false,    // Try Windows Toast and Growl first?
    customPath: undefined   // Relative/Absolute path if you want to use your fork of notifu
});

toasted.notify(
    {
        title: undefined,
        message: undefined,
        sound: false,       // true | false.
        time: 5000,         // How long to show balloon in ms
        wait: false,        // Wait for User Action against Notification
        type: 'info'        // The notification type : info | warn | error
    },
    ( error, response ) =>
    {
        console.log( response );
    }
);


NotifySend

  • A Node.js wrapper for sending notifications to users on Linux
  • Code available at: node_modules\toasted-notifier\notifiers\notifysend.js


[!NOTE] notify-send doesn't support the wait flag. See flags and options on the man page notify-send


const NotifySend = require('toasted-notifier').NotifySend;

const toasted = new NotifySend();

toasted.notify(
    {
        title: 'A Title',
        message: 'Hello to you',
        icon: __dirname + '/example_1.png',

        wait: false,        // Defaults no expire time set. If true expire time of 5 seconds is used. not supported by Windows Toasters
        timeout: 10,        // Alias for expire-time, time etc. Time before notify-send expires. Defaults to 10 seconds.

        // other notify-send flags:
        'app-name': 'toasted-notifier',
        urgency: undefined,
        category: undefined,
        hint: undefined
    }
);



appID support

Windows Toast notifications will show the name of the application calling the notification at the top of each popup. Out-of-box, the application name will be NtfyToast.

With the Windows Fall Creators Update, you may modify the application name notifications on Windows 10 / 11 by supplying an appID to your notification javascript code. The appID must be the id assigned to the executable you wish to define that will show for the name at the top of the notification.

If you wish to brand notifications with your own application name, then there are a few steps you must complete.


Create App Shortcut

You must create a windows shortcut (.lnk) within your windows Start Menu. This is a requirement by Microsoft.

The package used by Toasted Notifier for Windows 10 & 11 notifications (ntfy-toast); includes a command which will help you create the shortcut link automatically. To do this, open Command Prompt and run the command:

X:\path\to\node\project\node_modules\toasted-notifier\vendor\ntfyToast\ntfytoast.exe -install "MyApp\MyApp.lnk" "C:\path\to\myApp.exe" "My.APP_ID"


Argument Description
"MyApp\MyApp.lnk" Where the lnk shortcut will be placed.

C:\Users\USER\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\MyApp\MyApp.lnk
"C:\path\to\myApp.exe" Path to the executable you want to show the name for at the top of notifications
"My.APP_ID" Your .exe app id


To get the appID for the application you want to use, you can open Powershell and run the command:

get-StartApps | Where-Object {$_.Name -like '*YourAppName*'}


In our example, we can run

get-StartApps | Where-Object {$_.Name -like '*Ntfytoast*'}


Which returns the following:

Name          AppID
----          -----
ntfytoast     com.ntfytoast.id


This means that if I wanted to use NtfyToast as the app which sends notifications, my final command would be:

X:\path\to\node\project\node_modules\toasted-notifier\vendor\ntfyToast\ntfytoast.exe -install "Ntfytoast\Ntfytoast.lnk" "C:\path\to\ntfytoast.exe" "com.ntfytoast.id"


When the .lnk is created, it will be placed in:

C:\Users\USER\AppData\Roaming\Microsoft\Windows\Start Menu\Programs



Call App

Now that you have your app shortcut created, you can simply call the app every time you want to send a notification using appID. Remember to use your own app's id.

const WindowsToaster = require('toasted-notifier').WindowsToaster;

const toasted = new WindowsToaster({
    withFallback: false,            // Fallback to Growl or Balloons?
    customPath: undefined           // Relative/Absolute path if you want to use your fork of SnoreToast.exe
});

toasted.notify(
    {
        title: undefined,               // String           | Required
        message: undefined,             // String           | Required if remove is not defined
        icon: undefined,                // String           | Absolute path to Icon
        sound: false,                   // Bool or String   | (as defined by http://msdn.microsoft.com/en-us/library/windows/apps/hh761492.aspx)
        id: undefined,                  // Number           | ID to use for closing notification.
        appID: 'com.ntfytoast.id',      // String           | App.ID and app Name. Defaults to no value, causing SnoreToast text to be visible.
        remove: undefined,              // Number           | Refer to previously created notification to close.
        install: undefined              // String           | <path, application, app id> |  Creates a shortcut <path> in the start menu which point to the executable <application>, appID used for the notifications.
    },
    ( error, response ) =>
    {
        console.log( response );
    }
);


With the above code, we have specified an appID on the following line:

    appID: 'com.ntfytoast.id',



Help

The following is a list of questions or troubleshooting that may help you with implementing this node package.


How to change text NtfyToast at the top of notifications

In order to change the text NtfyToast, you must supply an -appID. Windows Toast notifications require that you provide an application id for a valid Windows application before Windows will allow you to link another program.

For instructions on accomplishing this, read the section appID support


Can't use Windows Toast notifications in WSL2

Ntfy makes use of a 3rd party package for Windows notifications to work. You must change the permissions on the Ntfy vendor .exe in order for it to work properly.

chmod +x node_modules/toasted-notifier/vendor/ntfyToast/ntfytoast.exe


You can add a postinstall action in the package.json:

 "scripts": {
        "postinstall": "chmod +x node_modules/toasted-notifier/vendor/ntfyToast/ntfytoast.exe
  }


Distributing with Electron

If you package your Electron based app as an asar; toasted-notifier will fail to load. This is because of how a asar package works. You cannot execute a binary from within an asar package.

The solution is that when packaging the app into an asar, make sure you --unpack the vendor/ folder of toasted-notifier/ so that the module still has access to the notification vendor binaries.

You can do so with the following command:

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


Or if you use electron-builder without using asar directly; append build object to your package.json as below:

...
build: {
  asarUnpack: [
    './node_modules/toasted-notifier/**/*',
  ]
},
...


Using Webpack

When using toasted-notifier inside of webpack, you must add the snippet below to your webpack.config.js.

node: {
  __filename: true,
  __dirname: true
}

This is necessary because toasted-notifier loads the notifiers from a binary, and needs a relative file path. When webpack compiles the modules, it suppresses file directories, causing toasted-notifier to error on certain platforms.


Windows: Where are files / .lnk files placed

In order for you to make your own custom application name appear at the top of a notification, you must create a .lnk in your Windows start menu. More about this is outlined in the section AppID Support


If you need to delete any of the generated .lnk files, you can find them in the following locations:

  • C:\ProgramData\Microsoft\Windows\Start Menu\Programs
  • C:\Users\YOURUSERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs


Toasted-notifier will also cache logo.png in:

  • C:\Users\YOURUSERNAME\AppData\Local\Temp\ntfytoast


Delete any folders named NtfyToast, or whatever your custom app name is.


Header icon broken / missing / default

If you show a notification and notice that the far top-left icon next to the app name is either missing or is showing a default application icon, you may need to clear your start menu .lnk file.


Go to the following folders, and delete the NtfyToast/ folder.

  • C:\ProgramData\Microsoft\Windows\Start Menu\Programs\NtfyToast\
  • C:\Users\YOURUSERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\NtfyToast\


If you are using a custom application, search for the app name as a folder, and delete that folder.


Usage in tmux session

When using toasted-notifier within a tmux session, it can cause the system to abruptly hang. To solve this issue:

  • Upgrade tmux from 1.9a to 2.0 with brew update && brew upgrade tmux
  • Install reattach-to-user-namespace with brew update && brew install reattach-to-user-namespace
  • Open ~/.tmux.conf and add the following lines:
      # Reattach each new window to the user bootstrap namespace
  # https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard
  set -g default-command "which reattach-to-user-namespace > /dev/null && reattach-to-user-namespace -l $SHELL || $SHELL -l"