toasted-notifier
v10.1.0
Push notifications in NodeJS for MacOS, Windows 7 - 11, and Linux (Growl as fallback)
0/weekUpdated 8 months agoMITUnpacked: 4.7 MB
Published by Aetherinox
npm install toasted-notifier♾️ Toasted Notifier ♾️
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
[![Version][badge-version-gh]][link-version-gh] [![Build Status][badge-build]][link-build] [![Downloads][badge-downloads-gh]][link-downloads-gh] [![Size][badge-size-gh]][badge-size-gh] [![Last Commit][badge-commit]][badge-commit]
---
- About
- What is ntfy-toast
- Features
- Install
- Usage
- Cross-Platform Advanced Usage
- Fine-grained Control
- Specific Vendor Documentation
- NotificationCenter
- Sounds
- Custom Path
- Spotlight
- WindowsToaster
- Notifications Not Working
- Windows 10 Fall Creators Update (Version 1709):
- Growl
- WindowsBalloon
- NotifySend
- appID support
- Create App Shortcut
- Call App
- Help
- How to change text NtfyToast at the top of notifications
- Can't use Windows Toast notifications in WSL2
- Distributing with Electron
- Using Webpack
- Windows: Where are files / .lnk files placed
- Header icon broken / missing / default
- Usage in tmux session
---
About
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
- notify-osd or libnotify-bin must be installed
- Ubuntu should have this by default
- Windows 8 - 11: ntfy-toast
- Windows 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
What is ntfy-toast
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.
---
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:
``shell`
npm install --save toasted-notifier
---
Usage
Example code for implementing notifications:
Cross-Platform Advanced Usage
This format can be used for all notification vendors _(Windows, Linux, Mac)_
`javascript
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`
});
Fine-grained Control
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.
`javascript
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:
`javascript
// 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:
---
- NotificationCenter
- WindowToaster
- Growl
- WindowsBalloon
- NotifySend
---
$3
- 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
, you can do anything terminal-notifier can by passing properties to the method.
- if terminal-notifier says -message, you can do {message: 'Foo'}
- if 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.
javascript
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. 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
. 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:
- Example: specific Notification Centers
- Example: input.
---
#### 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
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
$3
- A Node.js wrapper for Windows 7, 8, 10, and 11 notifications.
- Code available at:
Note: There are limitations for images in native Windows 8 notifications:
- Image must be a
image
- Image must be smaller than 1024×1024px
- Image must be less than
- Image must be specified using an These limitations are due to the Toast notification system. A good tip is to use something like
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: NtfyToast is the library used by 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:
`powershell`
get-StartApps | Where-Object {$_.Name -like 'YourAppName'}
In our example, we can run
`powershell`
get-StartApps | Where-Object {$_.Name -like 'Ntfytoast'}
Which returns the following:
`console`
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:
`javascript
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 |
},
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.
$3
- 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
javascript
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).
});
`
$3
- A Node.js wrapper for earlier versions of Windows such as Windows XP / 7.
- Code available at:
- Uses the 3rd party library Notifu, located at:
- View Notifu Project
javascript
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);
}
);
`
$3
- A Node.js wrapper for sending notifications to users on Linux
- Code available at:
> [!NOTE]
> notify-send doesn't support the
flag.
> See flags and options on the man page notify-send
`javascript
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
}
);
`
---
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
, 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.
$3
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:
`shell
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 |
| --- | --- |
|
| 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:
`powershell
get-StartApps | Where-Object {$_.Name -like 'YourAppName'}
`
In our example, we can run
powershell
get-StartApps | Where-Object {$_.Name -like 'Ntfytoast'}
`
Which returns the following:
console
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
is created, it will be placed in:
`
C:\Users\USER\AppData\Roaming\Microsoft\Windows\Start Menu\Programs
$3
Now that you have your app shortcut created, you can simply call the app every time you want to send a notification using . Remember to use your own app's id.`javascript
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 | | Creates a shortcut in the start menu which point to the executable , appID used for the notifications.
},
function (error, response) {
console.log(response);
}
);
`
With the above code, we have specified an
on the following line:
`javascript
appID: 'com.ntfytoast.id',
`
---
Help
$3
In order to change the text , 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
$3
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.`shell
chmod +x node_modules/toasted-notifier/vendor/ntfyToast/ntfytoast.exe
`
You can add a
action in the package.json:
`yml
"scripts": {
"postinstall": "chmod +x node_modules/toasted-notifier/vendor/ntfyToast/ntfytoast.exe
}
`
$3
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
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:
`shell
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
as below:`
...
build: {
asarUnpack: [
'./node_modules/toasted-notifier/*/',
]
},
...
$3
When using toasted-notifier inside of webpack, you must add the snippet below to your .`javascript
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.
$3
In order for you to make your own custom application name appear at the top of a notification, you must create a 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
-
Toasted-notifier will also cache
in:
- C:\Users\YOURUSERNAME\AppData\Local\Temp\ntfytoast
Delete any folders named
, or whatever your custom app name is.
$3
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\
-
If you are using a custom application, search for the app name as a folder, and delete that folder.
$3
When using toasted-notifier within a tmux session, it can cause the system to abruptly hang. To solve this issue:- Upgrade tmux from
to 2.0 with brew update && brew upgrade tmux
- Install reattach-to-user-namespace with
- Open 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"
---
[link-general-npm]: https://npmjs.com
[link-general-nodejs]: https://nodejs.org
[link-npmtrends]: http://npmtrends.com/toasted-notifier
[badge-version-gh]: https://img.shields.io/github/v/tag/Aetherinox/toasted-notifier?logo=GitHub&label=Version&color=ba5225
[link-version-gh]: https://github.com/Aetherinox/toasted-notifier/releases
[badge-version-npm]: https://img.shields.io/npm/v/toasted-notifier?logo=npm&label=Version&color=ba5225
[link-version-npm]: https://npmjs.com/package/toasted-notifier
[badge-license-mit]: https://img.shields.io/badge/MIT-FFF?logo=creativecommons&logoColor=FFFFFF&label=License&color=9d29a0
[link-license-mit]: https://github.com/Aetherinox/toasted-notifier/blob/main/LICENSE
[badge-build]: https://img.shields.io/github/actions/workflow/status/Aetherinox/toasted-notifier/npm-publish.yml?logo=github&logoColor=FFFFFF&label=Build&color=%23278b30
[link-build]: https://github.com/Aetherinox/toasted-notifier/actions/workflows/npm-publish.yml
[badge-downloads-gh]: https://img.shields.io/github/downloads/Aetherinox/toasted-notifier/total?logo=github&logoColor=FFFFFF&label=Downloads&color=376892
[link-downloads-gh]: https://github.com/Aetherinox/toasted-notifier/releases
[badge-downloads-npm]: https://img.shields.io/npm/dw/%40aetherinox%2Ftoasted-notifier?logo=npm&&label=Downloads&color=376892
[link-downloads-npm]: https://npmjs.com/package/toasted-notifier
[badge-size-gh]: https://img.shields.io/github/repo-size/Aetherinox/toasted-notifier?logo=github&label=Size&color=59702a
[link-size-gh]: https://github.com/Aetherinox/toasted-notifier/releases
[badge-size-npm]: https://img.shields.io/npm/unpacked-size/toasted-notifier/latest?logo=npm&label=Size&color=59702a
[link-size-npm]: https://npmjs.com/package/toasted-notifier
[badge-coverage]: https://img.shields.io/codecov/c/github/Aetherinox/toasted-notifier?token=MPAVASGIOG&logo=codecov&logoColor=FFFFFF&label=Coverage&color=354b9e
[link-coverage]: https://codecov.io/github/Aetherinox/toasted-notifier
[badge-all-contributors]: https://img.shields.io/github/all-contributors/Aetherinox/toasted-notifier?logo=contributorcovenant&color=de1f6f&label=contributors
[link-all-contributors]: https://github.com/all-contributors/all-contributors
[badge-tests]: https://img.shields.io/github/actions/workflow/status/Aetherinox/toasted-notifier/npm-tests.yml?logo=github&label=Tests&color=2c6488
[link-tests]: https://github.com/Aetherinox/toasted-notifier/actions/workflows/tests.yml
[badge-commit]: https://img.shields.io/github/last-commit/Aetherinox/toasted-notifier?logo=conventionalcommits&logoColor=FFFFFF&label=Last%20Commit&color=313131
[link-commit]: https://github.com/Aetherinox/toasted-notifier/commits/main/