1 | # node-notifier [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url]
|
2 |
|
3 | Send cross platform native notifications using Node.js. Notification Center for macOS,
|
4 | `notify-osd`/`libnotify-bin` for Linux, Toasters for Windows 8/10, or taskbar balloons for
|
5 | earlier Windows versions. Growl is used if none of these requirements are met.
|
6 | [Works well with Electron](#within-electron-packaging).
|
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 |
|
33 | - **macOS**: >= 10.8 for native notifications, or Growl if earlier.
|
34 | - **Linux**: `notify-osd` or `libnotify-bin` installed (Ubuntu should have this by default)
|
35 | - **Windows**: >= 8, or task bar balloons for Windows < 8. Growl as fallback. Growl takes precedence over Windows balloons.
|
36 | - **General Fallback**: Growl
|
37 |
|
38 | See [documentation and flow chart for reporter choice](./DECISION_FLOW.md).
|
39 |
|
40 | ## Install
|
41 |
|
42 | ```shell
|
43 | npm install --save node-notifier
|
44 | ```
|
45 |
|
46 | ## <abbr title="Command Line Interface">CLI</abbr>
|
47 |
|
48 | <abbr title="Command Line Interface">CLI</abbr> has moved to separate project:
|
49 | <https://github.com/mikaelbr/node-notifier-cli>
|
50 |
|
51 | ## Cross-Platform Advanced Usage
|
52 |
|
53 | Standard usage, with cross-platform fallbacks as defined in the
|
54 | [reporter flow chart](./DECISION_FLOW.md). All of the options
|
55 | below will work in some way or another on all platforms.
|
56 |
|
57 | ```javascript
|
58 | const notifier = require('node-notifier');
|
59 | const path = require('path');
|
60 |
|
61 | notifier.notify(
|
62 | {
|
63 | title: 'My awesome title',
|
64 | message: 'Hello from node, Mr. User!',
|
65 | icon: path.join(__dirname, 'coulson.jpg'), // Absolute path (doesn't work on balloons)
|
66 | sound: true, // Only Notification Center or Windows Toasters
|
67 | wait: true // Wait with callback, until user action is taken against notification
|
68 | },
|
69 | function(err, response) {
|
70 | // Response is response from notification
|
71 | }
|
72 | );
|
73 |
|
74 | notifier.on('click', function(notifierObject, options, event) {
|
75 | // Triggers if `wait: true` and user clicks notification
|
76 | });
|
77 |
|
78 | notifier.on('timeout', function(notifierObject, options) {
|
79 | // Triggers if `wait: true` and notification closes
|
80 | });
|
81 | ```
|
82 |
|
83 | If you want super fine-grained control, you can customize each reporter individually,
|
84 | allowing you to tune specific options for different systems.
|
85 |
|
86 | See below for documentation on each reporter.
|
87 |
|
88 | **Example:**
|
89 |
|
90 | ```javascript
|
91 | const NotificationCenter = require('node-notifier/notifiers/notificationcenter');
|
92 | new NotificationCenter(options).notify();
|
93 |
|
94 | const NotifySend = require('node-notifier/notifiers/notifysend');
|
95 | new NotifySend(options).notify();
|
96 |
|
97 | const WindowsToaster = require('node-notifier/notifiers/toaster');
|
98 | new WindowsToaster(options).notify();
|
99 |
|
100 | const Growl = require('node-notifier/notifiers/growl');
|
101 | new Growl(options).notify();
|
102 |
|
103 | const WindowsBalloon = require('node-notifier/notifiers/balloon');
|
104 | new WindowsBalloon(options).notify();
|
105 | ```
|
106 |
|
107 | Or, if you are using several reporters (or you're lazy):
|
108 |
|
109 | ```javascript
|
110 | // NOTE: Technically, this takes longer to require
|
111 | const nn = require('node-notifier');
|
112 |
|
113 | new nn.NotificationCenter(options).notify();
|
114 | new nn.NotifySend(options).notify();
|
115 | new nn.WindowsToaster(options).notify(options);
|
116 | new nn.WindowsBalloon(options).notify(options);
|
117 | new nn.Growl(options).notify(options);
|
118 | ```
|
119 |
|
120 | ## Contents
|
121 |
|
122 | - [Notification Center documentation](#usage-notificationcenter)
|
123 | - [Windows Toaster documentation](#usage-windowstoaster)
|
124 | - [Windows Balloon documentation](#usage-windowsballoon)
|
125 | - [Growl documentation](#usage-growl)
|
126 | - [Notify-send documentation](#usage-notifysend)
|
127 |
|
128 | ### Usage: `NotificationCenter`
|
129 |
|
130 | Same usage and parameter setup as [**`terminal-notifier`**](https://github.com/julienXX/terminal-notifier).
|
131 |
|
132 | Native Notification Center requires macOS version 10.8 or higher. If you have
|
133 | an earlier version, Growl will be the fallback. If Growl isn't installed, an
|
134 | error will be returned in the callback.
|
135 |
|
136 | #### Example
|
137 |
|
138 | Because `node-notifier` wraps around [**`terminal-notifier`**](https://github.com/julienXX/terminal-notifier),
|
139 | you can do anything `terminal-notifier` can, just by passing properties to the `notify`
|
140 | method.
|
141 |
|
142 | For example:
|
143 |
|
144 | - if `terminal-notifier` says `-message`, you can do `{message: 'Foo'}`
|
145 | - if `terminal-notifier` says `-list ALL`, you can do `{list: 'ALL'}`.
|
146 |
|
147 | Notification is the primary focus of this module, so listing and activating do work,
|
148 | but they aren't documented.
|
149 |
|
150 | ### All notification options with their defaults:
|
151 |
|
152 | ```javascript
|
153 | const NotificationCenter = require('node-notifier').NotificationCenter;
|
154 |
|
155 | var notifier = new NotificationCenter({
|
156 | withFallback: false, // Use Growl Fallback if <= 10.8
|
157 | customPath: void 0 // Relative/Absolute path to binary if you want to use your own fork of terminal-notifier
|
158 | });
|
159 |
|
160 | notifier.notify(
|
161 | {
|
162 | title: void 0,
|
163 | subtitle: void 0,
|
164 | message: void 0,
|
165 | sound: false, // Case Sensitive string for location of sound file, or use one of macOS' native sounds (see below)
|
166 | icon: 'Terminal Icon', // Absolute Path to Triggering Icon
|
167 | contentImage: void 0, // Absolute Path to Attached Image (Content Image)
|
168 | open: void 0, // URL to open on Click
|
169 | wait: false, // Wait for User Action against Notification or times out. Same as timeout = 5 seconds
|
170 |
|
171 | // New in latest version. See `example/macInput.js` for usage
|
172 | timeout: 5, // Takes precedence over wait if both are defined.
|
173 | closeLabel: void 0, // String. Label for cancel button
|
174 | actions: void 0, // String | Array<String>. Action label or list of labels in case of dropdown
|
175 | dropdownLabel: void 0, // String. Label to be used if multiple actions
|
176 | reply: false // Boolean. If notification should take input. Value passed as third argument in callback and event emitter.
|
177 | },
|
178 | function(error, response, metadata) {
|
179 | console.log(response, metadata);
|
180 | }
|
181 | );
|
182 | ```
|
183 |
|
184 | ---
|
185 |
|
186 | **Note:** The `wait` option is shorthand for `timeout: 5`. This just sets a timeout
|
187 | for 5 seconds. It does _not_ make the notification sticky!
|
188 |
|
189 | Without `wait` or `timeout`, notifications are just fired and forgotten. They don't
|
190 | wait for any response.
|
191 |
|
192 | To make notifications wait for a response (like activation/click), you must define
|
193 | a `timeout`.
|
194 |
|
195 | _Exception:_ If `reply` is defined, it's recommended to set `timeout` to a either
|
196 | high value, or to nothing at all.
|
197 |
|
198 | ---
|
199 |
|
200 | **For macOS notifications: `icon`, `contentImage`, and all forms of `reply`/`actions` require macOS 10.9.**
|
201 |
|
202 | Sound can be one of these: `Basso`, `Blow`, `Bottle`, `Frog`, `Funk`, `Glass`,
|
203 | `Hero`, `Morse`, `Ping`, `Pop`, `Purr`, `Sosumi`, `Submarine`, `Tink`.
|
204 |
|
205 | If `sound` is simply `true`, `Bottle` is used.
|
206 |
|
207 | ---
|
208 |
|
209 | **See Also:**
|
210 |
|
211 | - [Example: specific Notification Centers](./example/advanced.js)
|
212 | - [Example: input](./example/macInput.js).
|
213 |
|
214 | ---
|
215 |
|
216 | **Custom Path clarification**
|
217 |
|
218 | `customPath` takes a value of a relative or absolute path to the binary of your
|
219 | fork/custom version of **`terminal-notifier`**.
|
220 |
|
221 | **Example:** `./vendor/mac.noindex/terminal-notifier.app/Contents/MacOS/terminal-notifier`
|
222 |
|
223 | **Spotlight clarification**
|
224 |
|
225 | `terminal-notifier.app` resides in a `mac.noindex` folder to prevent Spotlight from indexing the app.
|
226 |
|
227 | ### Usage: `WindowsToaster`
|
228 |
|
229 | **Note:** There are some limitations for images in native Windows 8 notifications:
|
230 |
|
231 | - The image must be a PNG image
|
232 | - The image must be smaller than 1024×1024 px
|
233 | - The image must be less than 200kb
|
234 | - The image must be specified using an absolute path
|
235 |
|
236 | These limitations are due to the Toast notification system. A good tip is to use
|
237 | something like `path.join` or `path.delimiter` to keep your paths cross-platform.
|
238 |
|
239 | From [mikaelbr/gulp-notify#90 (comment)](https://github.com/mikaelbr/gulp-notify/issues/90#issuecomment-129333034)
|
240 |
|
241 | > You can make it work by going to System > Notifications & Actions. The 'toast'
|
242 | > app needs to have Banners enabled. (You can activate banners by clicking on the
|
243 | > 'toast' app and setting the 'Show notification banners' to On)
|
244 |
|
245 | ---
|
246 |
|
247 | **Windows 10 Fall Creators Update (Version 1709) Note:**
|
248 |
|
249 | With the Fall Creators Update, Notifications on Windows 10 will only work as
|
250 | expected if the correct `appID` is specified. Your `appID` must be exactly the same
|
251 | value that was registered during the installation of your app.
|
252 |
|
253 | You can find the ID of your App by searching the registry for the `appID` you
|
254 | specified at installation of your app. For example: If you use the squirrel
|
255 | framework, your `appID` will be something like `com.squirrel.your.app`.
|
256 |
|
257 | The default behaviour is to have the underlying toaster applicaton as `appId`.
|
258 | This works as expected, but shows `SnoreToast` as text in the notification.
|
259 |
|
260 | [**Snoretoast**](https://github.com/KDE/snoretoast) is used to get native Windows Toasts!
|
261 |
|
262 | ```javascript
|
263 | const WindowsToaster = require('node-notifier').WindowsToaster;
|
264 |
|
265 | var notifier = new WindowsToaster({
|
266 | withFallback: false, // Fallback to Growl or Balloons?
|
267 | customPath: void 0 // Relative/Absolute path if you want to use your fork of SnoreToast.exe
|
268 | });
|
269 |
|
270 | notifier.notify(
|
271 | {
|
272 | title: void 0, // String. Required
|
273 | message: void 0, // String. Required if remove is not defined
|
274 | icon: void 0, // String. Absolute path to Icon
|
275 | sound: false, // Bool | String (as defined by http://msdn.microsoft.com/en-us/library/windows/apps/hh761492.aspx)
|
276 | wait: false, // Bool. Wait for User Action against Notification or times out
|
277 | id: void 0, // Number. ID to use for closing notification.
|
278 | appID: void 0, // String. App.ID and app Name. Defaults to no value, causing SnoreToast text to be visible.
|
279 | remove: void 0, // Number. Refer to previously created notification to close.
|
280 | 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.
|
281 | },
|
282 | function(error, response) {
|
283 | console.log(response);
|
284 | }
|
285 | );
|
286 | ```
|
287 |
|
288 | ### Usage: `Growl`
|
289 |
|
290 | ```javascript
|
291 | const Growl = require('node-notifier').Growl;
|
292 |
|
293 | var notifier = new Growl({
|
294 | name: 'Growl Name Used', // Defaults as 'Node'
|
295 | host: 'localhost',
|
296 | port: 23053
|
297 | });
|
298 |
|
299 | notifier.notify({
|
300 | title: 'Foo',
|
301 | message: 'Hello World',
|
302 | icon: fs.readFileSync(__dirname + '/coulson.jpg'),
|
303 | wait: false, // Wait for User Action against Notification
|
304 |
|
305 | // and other growl options like sticky etc.
|
306 | sticky: false,
|
307 | label: void 0,
|
308 | priority: void 0
|
309 | });
|
310 | ```
|
311 |
|
312 | See more information about using [growly](https://github.com/theabraham/growly/).
|
313 |
|
314 | ### Usage: `WindowsBalloon`
|
315 |
|
316 | For earlier versions of Windows, taskbar balloons are used (unless
|
317 | fallback is activated and Growl is running). The balloons notifier uses a great
|
318 | project called [**`notifu`**](http://www.paralint.com/projects/notifu/).
|
319 |
|
320 | ```javascript
|
321 | const WindowsBalloon = require('node-notifier').WindowsBalloon;
|
322 |
|
323 | var notifier = new WindowsBalloon({
|
324 | withFallback: false, // Try Windows Toast and Growl first?
|
325 | customPath: void 0 // Relative/Absolute path if you want to use your fork of notifu
|
326 | });
|
327 |
|
328 | notifier.notify(
|
329 | {
|
330 | title: void 0,
|
331 | message: void 0,
|
332 | sound: false, // true | false.
|
333 | time: 5000, // How long to show balloon in ms
|
334 | wait: false, // Wait for User Action against Notification
|
335 | type: 'info' // The notification type : info | warn | error
|
336 | },
|
337 | function(error, response) {
|
338 | console.log(response);
|
339 | }
|
340 | );
|
341 | ```
|
342 |
|
343 | See full usage on the [project homepage: **`notifu`**](http://www.paralint.com/projects/notifu/).
|
344 |
|
345 | ### Usage: `NotifySend`
|
346 |
|
347 | **Note:** `notify-send` doesn't support the `wait` flag.
|
348 |
|
349 | ```javascript
|
350 | const NotifySend = require('node-notifier').NotifySend;
|
351 |
|
352 | var notifier = new NotifySend();
|
353 |
|
354 | notifier.notify({
|
355 | title: 'Foo',
|
356 | message: 'Hello World',
|
357 | icon: __dirname + '/coulson.jpg',
|
358 |
|
359 | // .. and other notify-send flags:
|
360 | urgency: void 0,
|
361 | time: void 0,
|
362 | category: void 0,
|
363 | hint: void 0
|
364 | });
|
365 | ```
|
366 |
|
367 | See flags and options on the man page [`notify-send(1)`](http://manpages.ubuntu.com/manpages/gutsy/man1/notify-send.1.html)
|
368 |
|
369 | ## Thanks to OSS
|
370 |
|
371 | `node-notifier` is made possible through Open Source Software.
|
372 | A very special thanks to all the modules `node-notifier` uses.
|
373 |
|
374 | - [`terminal-notifier`](https://github.com/julienXX/terminal-notifier)
|
375 | - [`Snoretoast`](https://github.com/KDE/snoretoast)
|
376 | - [`notifu`](http://www.paralint.com/projects/notifu/)
|
377 | - [`growly`](https://github.com/theabraham/growly/)
|
378 |
|
379 | [![NPM downloads][npm-downloads]][npm-url]
|
380 |
|
381 | ## Common Issues
|
382 |
|
383 | ### Windows: `SnoreToast` text
|
384 |
|
385 | See note on "Windows 10 Fall Creators Update" in Windows section.
|
386 | _**Short answer:** update your `appId`._
|
387 |
|
388 | ### Use inside tmux session
|
389 |
|
390 | When using `node-notifier` within a tmux session, it can cause a hang in the system.
|
391 | This can be solved by following the steps described in [this comment](https://github.com/julienXX/terminal-notifier/issues/115#issuecomment-104214742)
|
392 |
|
393 | There’s even more info [here](https://github.com/mikaelbr/node-notifier/issues/61#issuecomment-163560801)
|
394 | <https://github.com/mikaelbr/node-notifier/issues/61#issuecomment-163560801>.
|
395 |
|
396 | ### macOS: Custom icon without Terminal icon
|
397 |
|
398 | Even if you define an icon in the configuration object for `node-notifier`, you will
|
399 | see a small Terminal icon in the notification (see the example at the top of this
|
400 | document).
|
401 |
|
402 | This is the way notifications on macOS work. They always show the icon of the
|
403 | parent application initiating the notification. For `node-notifier`, `terminal-notifier`
|
404 | is the initiator, and it has the Terminal icon defined as its icon.
|
405 |
|
406 | To define your custom icon, you need to fork `terminal-notifier` and build your
|
407 | custom version with your icon.
|
408 |
|
409 | See [Issue #71 for more info](https://github.com/mikaelbr/node-notifier/issues/71)
|
410 | <https://github.com/mikaelbr/node-notifier/issues/71>.
|
411 |
|
412 | ### Within Electron Packaging
|
413 |
|
414 | If packaging your Electron app as an `asar`, you will find `node-notifier` will fail to load.
|
415 |
|
416 | Due to the way asar works, you cannot execute a binary from within an `asar`.
|
417 | As a simple solution, when packaging the app into an asar please make sure you
|
418 | `--unpack` the `vendor/` folder of `node-notifier`, so the module still has access to
|
419 | the notification binaries.
|
420 |
|
421 | You can do so with the following command:
|
422 |
|
423 | ```bash
|
424 | asar pack . app.asar --unpack "./node_modules/node-notifier/vendor/**"
|
425 | ```
|
426 |
|
427 | ### Using with pkg
|
428 |
|
429 | For issues using with the pkg module. Check this issue out: https://github.com/mikaelbr/node-notifier/issues/220#issuecomment-425963752
|
430 |
|
431 | ### Using Webpack
|
432 |
|
433 | When using `node-notifier` inside of `webpack`, you must add the snippet below to your `webpack.config.js`.
|
434 |
|
435 | This is necessary because `node-notifier` loads the notifiers from a binary, so it
|
436 | needs a relative file path. When webpack compiles the modules, it supresses file
|
437 | directories, causing `node-notifier` to error on certain platforms.
|
438 |
|
439 | To fix this, you can configure webpack to keep the relative file directories.
|
440 | Do so by append the following code to your `webpack.config.js`:
|
441 |
|
442 | ```javascript
|
443 | node: {
|
444 | __filename: true,
|
445 | __dirname: true
|
446 | }
|
447 | ```
|
448 |
|
449 | ## License
|
450 |
|
451 | [MIT License](http://en.wikipedia.org/wiki/MIT_License)
|
452 |
|
453 | [npm-url]: https://npmjs.org/package/node-notifier
|
454 | [npm-image]: http://img.shields.io/npm/v/node-notifier.svg?style=flat
|
455 | [npm-downloads]: http://img.shields.io/npm/dm/node-notifier.svg?style=flat
|
456 | [travis-url]: http://travis-ci.org/mikaelbr/node-notifier
|
457 | [travis-image]: http://img.shields.io/travis/mikaelbr/node-notifier.svg?style=flat
|