Send cross platform native notifications using Node.js. Notification Center for macOS,
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
Show a native notification on macOS, Windows, Linux:
const notifier = ;// Stringnotifier;// Objectnotifier;
- macOS: >= 10.8 for native notifications, or Growl if earlier.
libnotify-bininstalled (Ubuntu should have this by default)
- Windows: >= 8, or task bar balloons for Windows < 8. Growl as fallback. Growl takes precedence over Windows balloons.
- General Fallback: Growl
npm install --save node-notifier
CLI has moved to separate project: https://github.com/mikaelbr/node-notifier-cli
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 some way or another on all platforms.
const notifier = ;const path = ;notifier;notifier;notifier;
If you want super fine-grained control, you can customize each reporter individually, allowing you to tune specific options for different systems.
See below for documentation on each reporter.
const NotificationCenter = ;options;const NotifySend = ;options;const WindowsToaster = ;options;const Growl = ;options;const WindowsBalloon = ;options;
Or, if you are using several reporters (or you're lazy):
// NOTE: Technically, this takes longer to requireconst nn = ;options;options;options;options;options;
- Notification Center documentation
- Windows Toaster documentation
- Windows Balloon documentation
- Growl documentation
- Notify-send documentation
Same usage and parameter setup as
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.
node-notifier wraps around
you can do anything
terminal-notifier can, just by passing properties to the
-message, you can do
-list ALL, you can do
Notification is the primary focus of this module, so listing and activating do work, but they aren't documented.
All notification options with their defaults:
const NotificationCenter = NotificationCenter;var notifier =withFallback: false // Use Growl Fallback if <= 10.8customPath: undefined // Relative/Absolute path to binary if you want to use your own fork of terminal-notifier;notifier;
wait option is shorthand for
timeout: 5. This just sets a timeout
for 5 seconds. It does not make the notification sticky!
As of Version 6.0 there is a default
timeout set of
10 to ensure that the application closes properly. In order to remove the
timeout and have an instantly closing notification (does not support actions), set
false. If you are using
action it is recommended to set
timeout to a high value to ensure the user has time to respond.
reply is defined, it's recommended to set
timeout to a either
high value, or to nothing at all.
For macOS notifications:
contentImage, and all forms of
actions require macOS 10.9.
Sound can be one of these:
sound is simply
Bottle is used.
Custom Path clarification
customPath takes a value of a relative or absolute path to the binary of your
fork/custom version of
terminal-notifier.app resides in a
mac.noindex folder to prevent Spotlight from indexing the app.
Note: There are some limitations for images in native Windows 8 notifications:
- The image must be a PNG image
- The image must be smaller than 1024×1024 px
- The image must be less than 200kb
- The image must be specified using an absolute path
These limitations are due to the Toast notification system. A good tip is to use
path.delimiter to keep your paths cross-platform.
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)
Windows 10 Fall Creators Update (Version 1709) Note:
Snoretoast is used to get native Windows Toasts!
The default behaviour is to have the underlying toaster applicaton as
This works as expected, but shows
SnoreToast as text in the notification.
With the Fall Creators Update, Notifications on Windows 10 will only work as
expected if a valid
appID is specified. Your
appID must be exactly the same
value that was registered during the installation of your app.
You can find the ID of your App by searching the registry for the
specified at installation of your app. For example: If you use the squirrel
appID will be something like
const WindowsToaster = WindowsToaster;var notifier =withFallback: false // Fallback to Growl or Balloons?customPath: undefined // Relative/Absolute path if you want to use your fork of SnoreToast.exe;notifier;
const Growl = Growl;var notifier =name: 'Growl Name Used' // Defaults as 'Node'host: 'localhost'port: 23053;notifier;
See more information about using growly.
For earlier versions of Windows, taskbar balloons are used (unless
fallback is activated and Growl is running). The balloons notifier uses a great
const WindowsBalloon = WindowsBalloon;var notifier =withFallback: false // Try Windows Toast and Growl first?customPath: undefined // Relative/Absolute path if you want to use your fork of notifu;notifier;
See full usage on the project homepage:
notify-send doesn't support the
const NotifySend = NotifySend;var notifier = ;notifier;
See flags and options on the man page
Thanks to OSS
node-notifier is made possible through Open Source Software.
A very special thanks to all the modules
See note on "Windows 10 Fall Creators Update" in Windows section.
Short answer: update your
Use inside tmux session
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
There’s even more info here https://github.com/mikaelbr/node-notifier/issues/61#issuecomment-163560801.
macOS: Custom icon without Terminal icon
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
This is the way notifications on macOS work. They always show the icon of the
parent application initiating the notification. For
is the initiator, and it has the 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.
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
As a simple solution, when packaging the app into an asar please make sure you
vendor/ folder of
node-notifier, so the module still has access to
the notification binaries.
You can do so with the following command:
asar pack . app.asar --unpack "./node_modules/node-notifier/vendor/**"
Using with pkg
For issues using with the pkg module. Check this issue out: https://github.com/mikaelbr/node-notifier/issues/220#issuecomment-425963752
node-notifier inside of
webpack, you must add the snippet below to your
This is necessary because
node-notifier loads the notifiers from a binary, so it
needs a relative file path. When webpack compiles the modules, it supresses file
node-notifier to error on certain platforms.
To fix this, you can configure webpack to keep the relative file directories.
Do so by append the following code to your
node:__filename: true__dirname: true