1 | # node-notifier [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][depstat-image]][depstat-url]
|
2 |
|
3 | A Node.js module for sending cross platform system notifications. Using
|
4 | Notification Center for macOS, notify-osd/libnotify-bin for Linux, Toasters for
|
5 | Windows 8/10, or taskbar Balloons for earlier Windows versions. If none of
|
6 | these requirements are met, Growl is used.
|
7 |
|
8 | ![macOS Screenshot](https://raw.githubusercontent.com/mikaelbr/node-notifier/master/example/mac.png)
|
9 | ![Native Windows Screenshot](https://raw.githubusercontent.com/mikaelbr/node-notifier/master/example/windows.png)
|
10 |
|
11 | ## Input Example macOS Notification Center
|
12 |
|
13 | ![Input Example](https://raw.githubusercontent.com/mikaelbr/node-notifier/master/example/input-example.gif)
|
14 |
|
15 | ## Quick Usage
|
16 |
|
17 | Show a native notification on macOS, Windows, Linux:
|
18 |
|
19 | ```javascript
|
20 | const notifier = require('node-notifier');
|
21 | // String
|
22 | notifier.notify('Message');
|
23 |
|
24 | // Object
|
25 | notifier.notify({
|
26 | 'title': 'My notification',
|
27 | 'message': 'Hello, there!'
|
28 | });
|
29 | ```
|
30 |
|
31 | ## Requirements
|
32 | - **macOS**: >= 10.8 or Growl if earlier.
|
33 | - **Linux**: `notify-osd` or `libnotify-bin` installed (Ubuntu should have this by default)
|
34 | - **Windows**: >= 8, task bar balloon if earlier or Growl if that is installed.
|
35 | - **General Fallback**: Growl
|
36 |
|
37 | Growl takes precedence over Windows balloons.
|
38 |
|
39 | See [documentation and flow chart for reporter choice](./DECISION_FLOW.md)
|
40 |
|
41 | ## Install
|
42 | ```
|
43 | $ npm install --save node-notifier
|
44 | ```
|
45 |
|
46 | ## Cross-Platform Advanced Usage
|
47 |
|
48 | Standard usage, with cross-platform fallbacks as defined in the
|
49 | [reporter flow chart](./DECISION_FLOW.md). All of the options
|
50 | below will work in a way or another on all platforms.
|
51 |
|
52 | ```javascript
|
53 | const notifier = require('node-notifier');
|
54 | const path = require('path');
|
55 |
|
56 | notifier.notify({
|
57 | title: 'My awesome title',
|
58 | message: 'Hello from node, Mr. User!',
|
59 | icon: path.join(__dirname, 'coulson.jpg'), // Absolute path (doesn't work on balloons)
|
60 | sound: true, // Only Notification Center or Windows Toasters
|
61 | wait: true // Wait with callback, until user action is taken against notification
|
62 | }, function (err, response) {
|
63 | // Response is response from notification
|
64 | });
|
65 |
|
66 | notifier.on('click', function (notifierObject, options) {
|
67 | // Triggers if `wait: true` and user clicks notification
|
68 | });
|
69 |
|
70 | notifier.on('timeout', function (notifierObject, options) {
|
71 | // Triggers if `wait: true` and notification closes
|
72 | });
|
73 | ```
|
74 |
|
75 | You can also specify what reporter you want to use if you
|
76 | want to customize it or have more specific options per system.
|
77 | See documentation for each reporter below.
|
78 |
|
79 | Example:
|
80 | ```javascript
|
81 | const NotificationCenter = require('node-notifier/notifiers/notificationcenter');
|
82 | new NotificationCenter(options).notify();
|
83 |
|
84 | const NotifySend = require('node-notifier/notifiers/notifysend');
|
85 | new NotifySend(options).notify();
|
86 |
|
87 | const WindowsToaster = require('node-notifier/notifiers/toaster');
|
88 | new WindowsToaster(options).notify();
|
89 |
|
90 | const Growl = require('node-notifier/notifiers/growl');
|
91 | new Growl(options).notify();
|
92 |
|
93 | const WindowsBalloon = require('node-notifier/notifiers/balloon');
|
94 | new WindowsBalloon(options).notify();
|
95 |
|
96 | ```
|
97 |
|
98 | Or if you are using several (or you are lazy):
|
99 | (note: technically, this takes longer to require)
|
100 |
|
101 | ```javascript
|
102 | const nn = require('node-notifier');
|
103 |
|
104 | new nn.NotificationCenter(options).notify();
|
105 | new nn.NotifySend(options).notify();
|
106 | new nn.WindowsToaster(options).notify(options);
|
107 | new nn.WindowsBalloon(options).notify(options);
|
108 | new nn.Growl(options).notify(options);
|
109 | ```
|
110 |
|
111 | ## Contents
|
112 |
|
113 | * [Notification Center documentation](#usage-notificationcenter)
|
114 | * [Windows Toaster documentation](#usage-windowstoaster)
|
115 | * [Windows Balloon documentation](#usage-windowsballoon)
|
116 | * [Growl documentation](#usage-growl)
|
117 | * [Notify-send documentation](#usage-notifysend)
|
118 |
|
119 |
|
120 | ### Usage NotificationCenter
|
121 |
|
122 | Same usage and parameter setup as [terminal-notifier](https://github.com/alloy/terminal-notifier).
|
123 |
|
124 | Native Notification Center requires macOS version 10.8 or higher. If you have
|
125 | an earlier version, Growl will be the fallback. If Growl isn't installed, an
|
126 | error will be returned in the callback.
|
127 |
|
128 |
|
129 | #### Example
|
130 |
|
131 | Wrapping around [terminal-notifier](https://github.com/alloy/terminal-notifier), you can
|
132 | do all terminal-notifier can do through properties to the `notify` method. E.g.
|
133 | if `terminal-notifier` says `-message`, you can do `{message: 'Foo'}`, or
|
134 | if `terminal-notifier` says `-list ALL`, you can do `{list: 'ALL'}`. Notification
|
135 | is the primary focus for this module, so listing and activating do work,
|
136 | but isn't documented.
|
137 |
|
138 | ### All notification options with their defaults:
|
139 |
|
140 | ```javascript
|
141 | const NotificationCenter = require('node-notifier').NotificationCenter;
|
142 |
|
143 | var notifier = new NotificationCenter({
|
144 | withFallback: false, // Use Growl Fallback if <= 10.8
|
145 | customPath: void 0 // Relative/Absolute path to binary if you want to use your own fork of terminal-notifier
|
146 | });
|
147 |
|
148 | notifier.notify({
|
149 | 'title': void 0,
|
150 | 'subtitle': void 0,
|
151 | 'message': void 0,
|
152 | 'sound': false, // Case Sensitive string for location of sound file, or use one of macOS' native sounds (see below)
|
153 | 'icon': 'Terminal Icon', // Absolute Path to Triggering Icon
|
154 | 'contentImage': void 0, // Absolute Path to Attached Image (Content Image)
|
155 | 'open': void 0, // URL to open on Click
|
156 | 'wait': false, // Wait for User Action against Notification or times out. Same as timeout = 5 seconds
|
157 |
|
158 | // New in latest version. See `example/macInput.js` for usage
|
159 | timeout: 5, // Takes precedence over wait if both are defined.
|
160 | closeLabel: void 0, // String. Label for cancel button
|
161 | actions: void 0, // String | Array<String>. Action label or list of labels in case of dropdown
|
162 | dropdownLabel: void 0, // String. Label to be used if multiple actions
|
163 | reply: false // Boolean. If notification should take input. Value passed as third argument in callback and event emitter.
|
164 | }, function(error, response, metadata) {
|
165 | console.log(response, metadata);
|
166 | });
|
167 | ```
|
168 |
|
169 | **Note:** `wait` option is shorthand for `timeout: 5` and doesn't make the notification sticky, but sets
|
170 | timeout for 5 seconds. Without `wait` or `timeout` notifications are just fired and forgotten Without
|
171 | given any response. To be able to listen for response (like activation/clicked), you have to define a timeout.
|
172 | 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.
|
173 |
|
174 | **For macOS notifications, icon and contentImage, and all forms of reply/actions requires macOS 10.9.**
|
175 |
|
176 | Sound can be one of these: `Basso`, `Blow`, `Bottle`, `Frog`, `Funk`, `Glass`,
|
177 | `Hero`, `Morse`, `Ping`, `Pop`, `Purr`, `Sosumi`, `Submarine`, `Tink`.
|
178 | If sound is simply `true`, `Bottle` is used.
|
179 |
|
180 | See [specific Notification Center example](./example/advanced.js).
|
181 |
|
182 | **Custom Path clarification**
|
183 |
|
184 | `customPath` takes a value of a relative or absolute path to the binary of your fork/custom version of terminal-notifier.
|
185 |
|
186 | Example: `./vendor/terminal-notifier.app/Contents/MacOS/terminal-notifier`
|
187 |
|
188 | ### Usage WindowsToaster
|
189 |
|
190 | **Note:** There are some limitations for images in native Windows 8 notifications:
|
191 | The image must be a PNG image, and cannot be over 1024x1024 px, or over over 200Kb.
|
192 | You also need to specify the image by using an absolute path. These limitations are
|
193 | due to the Toast notification system. A good tip is to use something like
|
194 | `path.join` or `path.delimiter` to have cross-platform pathing.
|
195 |
|
196 | **Windows 10 Note:** You might have to activate banner notification for the toast to show.
|
197 |
|
198 | From [mikaelbr/gulp-notify#90 (comment)](https://github.com/mikaelbr/gulp-notify/issues/90#issuecomment-129333034)
|
199 | > 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)
|
200 |
|
201 | [Snoretoast](https://github.com/KDE/snoretoast) is used to get native Windows Toasts!
|
202 |
|
203 | ```javascript
|
204 | const WindowsToaster = require('node-notifier').WindowsToaster;
|
205 |
|
206 | var notifier = new WindowsToaster({
|
207 | withFallback: false, // Fallback to Growl or Balloons?
|
208 | customPath: void 0 // Relative/Absolute path if you want to use your fork of SnoreToast.exe
|
209 | });
|
210 |
|
211 | notifier.notify({
|
212 | title: void 0, // String. Required
|
213 | message: void 0, // String. Required if remove is not defined
|
214 | icon: void 0, // String. Absolute path to Icon
|
215 | sound: false, // Bool | String (as defined by http://msdn.microsoft.com/en-us/library/windows/apps/hh761492.aspx)
|
216 | wait: false, // Bool. Wait for User Action against Notification or times out
|
217 | id: void 0, // Number. ID to use for closing notification.
|
218 | appID: void 0, // String. App.ID. Don't create a shortcut but use the provided app id.
|
219 | remove: void 0, // Number. Refer to previously created notification to close.
|
220 | install: void 0 // String (path, application, app id). Creates a shortcut <path> in the start menu which point to the executable <application>, appID used for the notifications.
|
221 | }, function(error, response) {
|
222 | console.log(response);
|
223 | });
|
224 | ```
|
225 |
|
226 | ### Usage Growl
|
227 |
|
228 | ```javascript
|
229 | const Growl = require('node-notifier').Growl;
|
230 |
|
231 | var notifier = new Growl({
|
232 | name: 'Growl Name Used', // Defaults as 'Node'
|
233 | host: 'localhost',
|
234 | port: 23053
|
235 | });
|
236 |
|
237 | notifier.notify({
|
238 | title: 'Foo',
|
239 | message: 'Hello World',
|
240 | icon: fs.readFileSync(__dirname + '/coulson.jpg'),
|
241 | wait: false, // Wait for User Action against Notification
|
242 |
|
243 | // and other growl options like sticky etc.
|
244 | sticky: false,
|
245 | label: void 0,
|
246 | priority: void 0
|
247 | });
|
248 | ```
|
249 |
|
250 | See more information about using
|
251 | [growly](https://github.com/theabraham/growly/).
|
252 |
|
253 | ### Usage WindowsBalloon
|
254 |
|
255 | For earlier Windows versions, the taskbar balloons are used (unless
|
256 | fallback is activated and Growl is running). For balloons, a great
|
257 | project called [notifu](http://www.paralint.com/projects/notifu/) is used.
|
258 |
|
259 | ```javascript
|
260 | const WindowsBalloon = require('node-notifier').WindowsBalloon;
|
261 |
|
262 | var notifier = new WindowsBalloon({
|
263 | withFallback: false, // Try Windows Toast and Growl first?
|
264 | customPath: void 0 // Relative/Absolute path if you want to use your fork of notifu
|
265 | });
|
266 |
|
267 | notifier.notify({
|
268 | title: void 0,
|
269 | message: void 0,
|
270 | sound: false, // true | false.
|
271 | time: 5000, // How long to show balloon in ms
|
272 | wait: false, // Wait for User Action against Notification
|
273 | type: 'info' // The notification type : info | warn | error
|
274 | }, function(error, response) {
|
275 | console.log(response);
|
276 | });
|
277 | ```
|
278 |
|
279 | See full usage on the [project homepage:
|
280 | notifu](http://www.paralint.com/projects/notifu/).
|
281 |
|
282 | ### Usage NotifySend
|
283 |
|
284 | Note: notify-send doesn't support the wait flag.
|
285 |
|
286 | ```javascript
|
287 | const NotifySend = require('node-notifier').NotifySend;
|
288 |
|
289 | var notifier = new NotifySend();
|
290 |
|
291 | notifier.notify({
|
292 | title: 'Foo',
|
293 | message: 'Hello World',
|
294 | icon: __dirname + '/coulson.jpg',
|
295 |
|
296 | // .. and other notify-send flags:
|
297 | urgency: void 0,
|
298 | time: void 0,
|
299 | category: void 0,
|
300 | hint: void 0,
|
301 | });
|
302 | ```
|
303 |
|
304 | See flags and options [on the man pages](http://manpages.ubuntu.com/manpages/gutsy/man1/notify-send.1.html)
|
305 |
|
306 | ## CLI
|
307 |
|
308 | CLI is moved to separate project: https://github.com/mikaelbr/node-notifier-cli
|
309 |
|
310 | ## Thanks to OSS
|
311 |
|
312 | `node-notifier` is made possible through Open Source Software. A very special thanks to all the modules `node-notifier` uses.
|
313 | * [terminal-notifier](https://github.com/alloy/terminal-notifier)
|
314 | * [Snoretoast](https://github.com/KDE/snoretoast)
|
315 | * [notifu](http://www.paralint.com/projects/notifu/)
|
316 | * [growly](https://github.com/theabraham/growly/)
|
317 |
|
318 | [![NPM downloads][npm-downloads]][npm-url]
|
319 |
|
320 | ## Common Issues
|
321 |
|
322 | ### Use inside tmux session
|
323 |
|
324 | 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
|
325 |
|
326 | See more info here: https://github.com/mikaelbr/node-notifier/issues/61#issuecomment-163560801
|
327 |
|
328 |
|
329 | ### Within Electron Packaging
|
330 |
|
331 | 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:
|
332 |
|
333 | ```bash
|
334 | asar pack . app.asar --unpack "./node_modules/node-notifier/vendor/**"
|
335 | ```
|
336 |
|
337 |
|
338 | ### Using Webpack
|
339 |
|
340 | 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`
|
341 |
|
342 | ```javascript
|
343 | node: {
|
344 | __filename: true,
|
345 | __dirname: true
|
346 | }
|
347 | ```
|
348 |
|
349 |
|
350 | ## License
|
351 |
|
352 | [MIT License](http://en.wikipedia.org/wiki/MIT_License)
|
353 |
|
354 | [npm-url]: https://npmjs.org/package/node-notifier
|
355 | [npm-image]: http://img.shields.io/npm/v/node-notifier.svg?style=flat
|
356 | [npm-downloads]: http://img.shields.io/npm/dm/node-notifier.svg?style=flat
|
357 |
|
358 | [travis-url]: http://travis-ci.org/mikaelbr/node-notifier
|
359 | [travis-image]: http://img.shields.io/travis/mikaelbr/node-notifier.svg?style=flat
|
360 |
|
361 | [depstat-url]: https://gemnasium.com/mikaelbr/node-notifier
|
362 | [depstat-image]: http://img.shields.io/gemnasium/mikaelbr/node-notifier.svg?style=flat
|