toasted-notifier
Advanced tools
Push notifications in NodeJS for MacOS, Windows 7 - 11, and Linux (Growl as fallback)
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
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.8 for native notifications, or Growl if earlier.Linux: notify-osd or libnotify-bin
Windows 8 - 11: ntfy-toastWindows 7 and earlier: Windows balloons
Other: Growl is used if none of these requirements are metntfy-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.
Simply install it using:
npm install --save toasted-notifier
Example 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:
node_modules\toasted-notifier\notifiers\notificationcenter.jsSince toasted-notifier wraps around terminal-notifier, you can do anything terminal-notifier can by passing properties to the method.
terminal-notifier says -message, you can do {message: 'Foo'}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.
},
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 ofreply/actionsrequire 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: trueis defined, set timeout to a high value, or to nothing at all.
When specifying a sound, you have the following options:
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.appnode_modules\toasted-notifier\notifiers\toaster.jsNote: There are limitations for images in native Windows 8 notifications:
PNG image1024×1024px200kbabsolute pathThese 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.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.
},
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.
node_modules\toasted-notifier\notifiers\growl.jsconst 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).
});
node_modules\toasted-notifier\notifiers\balloon.jsnode_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);
}
);
node_modules\toasted-notifier\notifiers\notifysend.js[!NOTE] notify-send doesn't support the
waitflag. 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.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
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',
NtfyToast at the top of notificationsIn 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.exe
You 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\ProgramsToasted-notifier will also cache logo.png in:
C:\Users\YOURUSERNAME\AppData\Local\Temp\ntfytoastDelete 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:
1.9a to 2.0 with brew update && brew upgrade tmuxbrew update && brew install reattach-to-user-namespace~/.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"
FAQs
Push notifications in NodeJS for MacOS, Windows 7 - 11, and Linux (Growl as fallback)
We found that toasted-notifier demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.