Toasted Notifier is a forked verison 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
- About
- Features
- Install
- Usage
Toasted Notifier allows you to send cross platform native notifications using Node.js. Works well with Electron.
The correct notification package will be used by Toasted Notifier depending on the end-user operating system:
MacOS: Notification Center>= 10.8for native notifications, or Growl if earlier.
Linux: notify-osd or libnotify-bin- notify-osd or libnotify-bin must be installed
- Ubuntu should have this by default
Windows 8 - 11: ntfy-toastWindows 7 and earlier: Windows balloons- Windows balloons for Windows < 8.
- Growl as fallback.
- Growl takes precedence over Windows balloons.
Other: Growl is used if none of these requirements are met
ntfy-toast is a package included in this repo, which services notifications for users running Windows 8 - 11.
It is based on SnoreToast, but has been updated with numerous 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-notifierExample code for implementing notifications:
This format can be used for all notification vendors (Windows, Linux, Mac)
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
},
function (err, 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 reporter; you can call them individually. This allows you to tune specific options for the different vendors.
See below for documentation on each reporter.
const NotificationCenter = require('toasted-notifier/notifiers/notificationcenter');
new NotificationCenter(options).notify();
const NotifySend = require('toasted-notifier/notifiers/notifysend');
new NotifySend(options).notify();
const WindowsToaster = require('toasted-notifier/notifiers/toaster');
new WindowsToaster(options).notify();
const Growl = require('toasted-notifier/notifiers/growl');
new Growl(options).notify();
const WindowsBalloon = require('toasted-notifier/notifiers/balloon');
new WindowsBalloon(options).notify();If you're using several reporters:
// 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:
- 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.
},
function (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 7, 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: NtfyToast is the library used by 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.
},
function (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
},
function (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
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.
},
function (error, response) {
console.log(response);
}
);With the above code, we have specified an appID on the following line:
appID: 'com.ntfytoast.id',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.
Is 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"