node-notifier
Send cross platform native notifications using Node.js. Notification Center for macOS, notify-osd/libnotify-bin for Linux, Toasters for Windows 8/10, or taskbar Balloons for earlier Windows versions. Growl is used if none of these requirements are met. Works well with electron.
Input Example macOS Notification Center
Quick Usage
Show a native notification on macOS, Windows, Linux:
const notifier = ;// Stringnotifier; // Objectnotifier;
Requirements
- macOS: >= 10.8 or Growl if earlier.
- Linux:
notify-osd
orlibnotify-bin
installed (Ubuntu should have this by default) - Windows: >= 8, task bar balloon for Windows < 8. Growl as fallback. Growl takes precedence over Windows balloons.
- General Fallback: Growl
See documentation and flow chart for reporter choice
Install
npm install --save node-notifier
Cross-Platform Advanced Usage
Standard usage, with cross-platform fallbacks as defined in the reporter flow chart. All of the options below will work in a way or another on all platforms.
const notifier = ;const path = ; notifier; notifier; notifier;
You can also specify what reporter you want to use if you want to customize it or have more specific options per system. See documentation for each reporter below.
Example:
const NotificationCenter = ;options; const NotifySend = ;options; const WindowsToaster = ;options; const Growl = ;options; const WindowsBalloon = ;options;
Or if you are using several (or you are lazy): (note: technically, this takes longer to require)
const nn = ; options;options;options;options;options;
Contents
- Notification Center documentation
- Windows Toaster documentation
- Windows Balloon documentation
- Growl documentation
- Notify-send documentation
Usage NotificationCenter
Same usage and parameter setup as terminal-notifier.
Native Notification Center requires macOS version 10.8 or higher. If you have an earlier version, Growl will be the fallback. If Growl isn't installed, an error will be returned in the callback.
Example
Wrapping around terminal-notifier, you can
do all terminal-notifier can do through properties to the notify
method. E.g.
if terminal-notifier
says -message
, you can do {message: 'Foo'}
, or
if terminal-notifier
says -list ALL
, you can do {list: 'ALL'}
. Notification
is the primary focus for this module, so listing and activating do work,
but isn't documented.
All notification options with their defaults:
const NotificationCenter = NotificationCenter; var notifier = withFallback: false // Use Growl Fallback if <= 10.8 customPath: void 0 // Relative/Absolute path to binary if you want to use your own fork of terminal-notifier; notifier;
Note: wait
option is shorthand for timeout: 5
and doesn't make the notification sticky, but sets
timeout for 5 seconds. Without wait
or timeout
notifications are just fired and forgotten Without
given any response. To be able to listen for response (like activation/clicked), you have to define a timeout.
This is not true if you have defined reply
. If using reply
it's recommended to set a high timeout or no timeout at all.
For macOS notifications, icon and contentImage, and all forms of reply/actions requires macOS 10.9.
Sound can be one of these: Basso
, Blow
, Bottle
, Frog
, Funk
, Glass
,
Hero
, Morse
, Ping
, Pop
, Purr
, Sosumi
, Submarine
, Tink
.
If sound is simply true
, Bottle
is used.
See specific Notification Center example. Also, see input example.
Custom Path clarification
customPath
takes a value of a relative or absolute path to the binary of your fork/custom version of terminal-notifier.
Example: ./vendor/terminal-notifier.app/Contents/MacOS/terminal-notifier
Usage WindowsToaster
Note: There are some limitations for images in native Windows 8 notifications:
The image must be a PNG image, and cannot be over 1024x1024 px, or over over 200Kb.
You also need to specify the image by 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 have cross-platform pathing.
Windows 10 Note: You might have to activate banner notification for the toast to show.
From mikaelbr/gulp-notify#90 (comment)
You can make it work by going to System > Notifications & Actions. The 'toast' app needs to have Banners enabled. (You can activate banners by clicking on the 'toast' app and setting the 'Show notification banners' to On)
Snoretoast is used to get native Windows Toasts!
const WindowsToaster = WindowsToaster; var notifier = withFallback: false // Fallback to Growl or Balloons? customPath: void 0 // Relative/Absolute path if you want to use your fork of SnoreToast.exe; notifier;
Usage Growl
const Growl = Growl; var notifier = name: 'Growl Name Used' // Defaults as 'Node' host: 'localhost' port: 23053; notifier;
See more information about using growly.
Usage WindowsBalloon
For earlier Windows versions, the taskbar balloons are used (unless fallback is activated and Growl is running). For balloons, a great project called notifu is used.
const WindowsBalloon = WindowsBalloon; var notifier = withFallback: false // Try Windows Toast and Growl first? customPath: void 0 // Relative/Absolute path if you want to use your fork of notifu; notifier;
See full usage on the project homepage: notifu.
Usage NotifySend
Note: notify-send doesn't support the wait flag.
const NotifySend = NotifySend; var notifier = ; notifier;
See flags and options on the man pages
CLI
CLI is moved to separate project: https://github.com/mikaelbr/node-notifier-cli
Thanks to OSS
node-notifier
is made possible through Open Source Software. A very special thanks to all the modules node-notifier
uses.
Common Issues
Use inside tmux session
When using node-notifier within a tmux session, it can cause a hang in the system. This can be solved by following the steps described in this comment: https://github.com/julienXX/terminal-notifier/issues/115#issuecomment-104214742
See more info here: https://github.com/mikaelbr/node-notifier/issues/61#issuecomment-163560801
Custom icon without terminal icon on macOS
Even if you define an icon in the configuration object for node-notifier
, you will see a small Terminal icon in the notification (see the example at the top of this document). This is the way notifications on macOS work, it always show the parent icon of the application initiating the notification. For node-notifier, terminal-notifier is the initiator and has Terminal icon defined as its icon. To define your custom icon, you need to fork terminal-notifier and build your custom version with your icon. See this issue for more info: https://github.com/mikaelbr/node-notifier/issues/71
Within Electron Packaging
If packaging your Electron app as an asar
, you will find node-notifier will fail to load. Due to the way asar works, you cannot execute a binary from within an asar. As a simple solution, when packaging the app into an asar please make sure you --unpack
the vendor folder of node-notifier, so the module still has access to the notification binaries. To do this, you can do so by using the following command:
asar pack . app.asar --unpack "./node_modules/node-notifier/vendor/**"
Using Webpack
When using node-notifier inside of webpack, you must add the following snippet to your webpack.config.js
. The reason this is required, is because node-notifier loads the notifiers from a binary, and so a relative file path is needed. When webpack compiles the modules, it supresses file directories, causing node-notifier to error on certain platforms. To fix/workaround this, you must tell webpack to keep the relative file directories, by doing so, append the following code to your webpack.config.js
node: __filename: true __dirname: true