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
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-osdorlibnotify-bin; which must be installed on your Linux system. - Ubuntu should have one of these packages by default
- Notifications will be shown using
- WindowToaster: Microsoft Windows 8, 9, 10, 11+
- WindowsBalloon: Windows XP, 7
- Growl as fallback if Windows Balloon notifications cannot be called
- Growl takes precedence over Windows balloons
- Growl: macOS, Windows
- This notification system is called if none of the requirements for the other notification vendors are met
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.
- 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
Simply install it using:
npm install --save toasted-notifierInformation 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:
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
});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.
/*
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);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 |
- 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-notifiersays-message, you can do{message: 'Foo'} - if
terminal-notifiersays-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.
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:
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
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
- 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
PNGimage - 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.
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:
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.idYou 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.
- 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).
});- 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 );
}
);- 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
}
);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.
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.idThis 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
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',The following is a list of questions or troubleshooting that may help you with implementing this node package.
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
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.exeYou can add a postinstall action in the package.json:
"scripts": {
"postinstall": "chmod +x node_modules/toasted-notifier/vendor/ntfyToast/ntfytoast.exe
}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/**/*',
]
},
...
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.
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\ProgramsC:\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.
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.
When using toasted-notifier within a tmux session, it can cause the system to abruptly hang. To solve this issue:
- Upgrade tmux from
1.9ato2.0withbrew update && brew upgrade tmux - Install reattach-to-user-namespace with
brew update && brew install reattach-to-user-namespace - Open
~/.tmux.confand 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"