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 notification. Using
|
4 | Notification Center for Mac, notify-osd for Linux, Toasters for
|
5 | Windows 8/10, or lovely taskbar Balloons for earlier Windows versions. If none of
|
6 | these requirements are met, be it older version of Windows or OS X,
|
7 | Growl is used.
|
8 |
|
9 | ![Mac Screenshot](https://github.com/mikaelbr/node-notifier/blob/master/example/mac.png)
|
10 | ![Native Windows Screenshot](https://github.com/mikaelbr/node-notifier/blob/master/example/windows.png)
|
11 | ![Growl Screenshot](https://github.com/mikaelbr/node-notifier/blob/master/example/growl.png)
|
12 |
|
13 | ## Easy Usage
|
14 |
|
15 | Show native notifications on Mac, Windows, Linux or using Growl!
|
16 |
|
17 | ```javascript
|
18 | var notifier = require('node-notifier');
|
19 | notifier.notify({
|
20 | 'title': 'My notification',
|
21 | 'message': 'Hello, there!'
|
22 | });
|
23 | ```
|
24 |
|
25 | ## Requirements
|
26 | - **Mac OS X**: >= 10.8 or Growl if earlier.
|
27 | - **Linux**: notify-osd installed (Ubuntu should have this by default)
|
28 | - **Windows**: >= 8, task bar balloon if earlier or Growl if that is installed.
|
29 | - **General Fallback**: Growl
|
30 |
|
31 | Growl takes precedence over Windows balloons.
|
32 |
|
33 | See [documentation and flow chart for reporter choice](./DECISION_FLOW.md)
|
34 |
|
35 | ## Install
|
36 | ```
|
37 | $ npm install --save node-notifier
|
38 | ```
|
39 |
|
40 | ## Cross-Platform Advanced Usage
|
41 |
|
42 | Standard usage, with cross-platform fallbacks as defined in the
|
43 | [reporter flow chart](./DECISION_FLOW.md). All of the options
|
44 | below will work in a way or another on all platforms.
|
45 |
|
46 | ```javascript
|
47 | var notifier = require('node-notifier');
|
48 | var path = require('path');
|
49 |
|
50 | notifier.notify({
|
51 | title: 'My awesome title',
|
52 | message: 'Hello from node, Mr. User!',
|
53 | icon: path.join(__dirname, 'coulson.jpg'), // absolute path (not balloons)
|
54 | sound: true, // Only Notification Center or Windows Toasters
|
55 | wait: true // wait with callback until user action is taken on notification
|
56 | }, function (err, response) {
|
57 | // response is response from notification
|
58 | });
|
59 |
|
60 | notifier.on('click', function (notifierObject, options) {
|
61 | // Happens if `wait: true` and user clicks notification
|
62 | });
|
63 |
|
64 | notifier.on('timeout', function (notifierObject, options) {
|
65 | // Happens if `wait: true` and notification closes
|
66 | });
|
67 | ```
|
68 |
|
69 | You can also specify what reporter you want to use if you
|
70 | want to customize it or have more specific options per system.
|
71 | See documentation for each reporter below.
|
72 |
|
73 | Example:
|
74 | ```javascript
|
75 | var NotificationCenter = require('node-notifier/notifiers/notificationcenter');
|
76 | new NotificationCenter(options).notify();
|
77 |
|
78 | var NotifySend = require('node-notifier/notifiers/notifysend');
|
79 | new NotifySend(options).notify();
|
80 |
|
81 | var WindowsToaster = require('node-notifier/notifiers/toaster');
|
82 | new WindowsToaster(options).notify();
|
83 |
|
84 | var Growl = require('node-notifier/notifiers/growl');
|
85 | new Growl(options).notify();
|
86 |
|
87 | var WindowsBalloon = require('node-notifier/notifiers/balloon');
|
88 | new WindowsBalloon(options).notify();
|
89 |
|
90 | ```
|
91 |
|
92 |
|
93 | Or if you are using several (or you are lazy):
|
94 | (note: technically, this takes longer to require)
|
95 |
|
96 | ```javascript
|
97 | var nn = require('node-notifier');
|
98 |
|
99 | new nn.NotificationCenter(options).notify();
|
100 | new nn.NotifySend(options).notify();
|
101 | new nn.WindowsToaster(options).notify(options);
|
102 | new nn.WindowsBalloon(options).notify(options);
|
103 | new nn.Growl(options).notify(options);
|
104 | ```
|
105 |
|
106 |
|
107 | ## Documentation
|
108 |
|
109 | * [Notification Center documentation](#usage-notificationcenter)
|
110 | * [Windows Toaster documentation](#usage-windowstoaster)
|
111 | * [Windows Balloon documentation](#usage-windowsballoon)
|
112 | * [Growl documentation](#usage-growl)
|
113 | * [Notify-send documentation](#usage-notifysend)
|
114 |
|
115 |
|
116 | ### Usage NotificationCenter
|
117 |
|
118 | Same usage and parameter setup as [terminal-notifier](https://github.com/alloy/terminal-notifier).
|
119 |
|
120 | Native Notification Center requires Mac OS X version 10.8 or higher. If you have
|
121 | earlier versions, Growl will be the fallback. If Growl isn't installed, an error
|
122 | will be returned in the callback.
|
123 |
|
124 |
|
125 | #### Example
|
126 |
|
127 | It is a wrapper around [terminal-notifier](https://github.com/alloy/terminal-notifier), and you can
|
128 | do all terminal-notifier can do through properties to the `notify` method. E.g.
|
129 | if `terminal-notifier` say `-message`, you can do `{message: 'Foo'}`, or
|
130 | if `terminal-notifier` say `-list ALL` you can do `{list: 'ALL'}`. Notification
|
131 | is the primary focus for this module, so listing and activating do work,
|
132 | but isn't documented.
|
133 |
|
134 | ### All notification options with their defaults:
|
135 |
|
136 | ```javascript
|
137 | var NotificationCenter = require('node-notifier').NotificationCenter;
|
138 |
|
139 | var notifier = new Notification({
|
140 | withFallback: false, // use Growl if <= 10.8?
|
141 | customPath: void 0 // Relative path if you want to use your fork of terminal-notifier
|
142 | });
|
143 |
|
144 | notifier.notify({
|
145 | 'title': void 0,
|
146 | 'subtitle': void 0,
|
147 | 'message': void 0,
|
148 | 'sound': false, // Case Sensitive string of sound file (see below)
|
149 | 'icon': 'Terminal Icon', // Set icon? (Absolute path to image)
|
150 | 'contentImage': void 0, // Attach image? (Absolute path)
|
151 | 'open': void 0, // URL to open on click
|
152 | 'wait': false // if wait for notification to end
|
153 | }, function(error, response) {
|
154 | console.log(response);
|
155 | });
|
156 | ```
|
157 |
|
158 | **For Mac OS notifications, icon and contentImage requires OS X 10.9.**
|
159 |
|
160 | Sound can be one of these: `Basso`, `Blow`, `Bottle`, `Frog`, `Funk`, `Glass`,
|
161 | `Hero`, `Morse`, `Ping`, `Pop`, `Purr`, `Sosumi`, `Submarine`, `Tink`. If
|
162 | sound is simply `true`, `Bottle` is used.
|
163 |
|
164 | See [specific Notification Center example](./example/advanced.js).
|
165 |
|
166 | ### Usage WindowsToaster
|
167 |
|
168 | **Note:** There are some limitations for images in native Windows 8 notifications:
|
169 | The image must be a PNG image, and cannot be over 1024x1024 px, or over over 200Kb.
|
170 | You also need to specify the image by using absolute path. These limitations are
|
171 | due to the Toast notification system. A good tip is to use something like
|
172 | `path.join` or `path.delimiter` to have cross-platform pathing.
|
173 |
|
174 | **Windows 10 Note:** You might have to activate banner notification for the toast to show.
|
175 |
|
176 | From [mikaelbr/gulp-notify#90 (comment)](https://github.com/mikaelbr/gulp-notify/issues/90#issuecomment-129333034)
|
177 | > 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)
|
178 |
|
179 | [toaster](https://github.com/nels-o/toaster) is used to get native Windows Toasts!
|
180 |
|
181 | ```javascript
|
182 | var WindowsToaster = require('node-notifier').WindowsToaster;
|
183 |
|
184 | var notifier = new WindowsToaster({
|
185 | withFallback: false, // Fallback to Growl or Balloons?
|
186 | customPath: void 0 // Relative path if you want to use your fork of toast.exe
|
187 | });
|
188 |
|
189 | notifier.notify({
|
190 | title: void 0,
|
191 | message: void 0,
|
192 | icon: void 0, // absolute path to an icon
|
193 | sound: false, // true | false.
|
194 | wait: false, // if wait for notification to end
|
195 | }, function(error, response) {
|
196 | console.log(response);
|
197 | });
|
198 | ```
|
199 |
|
200 | ### Usage Growl
|
201 |
|
202 | ```javascript
|
203 | var Growl = require('node-notifier').Growl;
|
204 |
|
205 | var notifier = new Growl({
|
206 | name: 'Growl Name Used', // Defaults as 'Node'
|
207 | host: 'localhost',
|
208 | port: 23053
|
209 | });
|
210 |
|
211 | notifier.notify({
|
212 | title: 'Foo',
|
213 | message: 'Hello World',
|
214 | icon: fs.readFileSync(__dirname + "/coulson.jpg"),
|
215 | wait: false, // if wait for user interaction
|
216 |
|
217 | // and other growl options like sticky etc.
|
218 | sticky: false,
|
219 | label: void 0,
|
220 | priority: void 0
|
221 | });
|
222 | ```
|
223 |
|
224 | See more information about using
|
225 | [growly](https://github.com/theabraham/growly/).
|
226 |
|
227 | ### Usage WindowsBalloon
|
228 |
|
229 | For earlier Windows versions, the taskbar balloons are used (unless
|
230 | fallback is activated and Growl is running). For balloons a great
|
231 | project called [notifu](http://www.paralint.com/projects/notifu/) is used.
|
232 |
|
233 | ```javascript
|
234 | var WindowsBalloon = require('node-notifier').WindowsBalloon;
|
235 |
|
236 | var notifier = new WindowsBalloon({
|
237 | withFallback: false, // Try Windows 8 and Growl first?
|
238 | customPath: void 0 // Relative path if you want to use your fork of notifu
|
239 | });
|
240 |
|
241 | notifier.notify({
|
242 | title: void 0,
|
243 | message: void 0,
|
244 | sound: false, // true | false.
|
245 | time: 5000, // How long to show balloons in ms
|
246 | wait: false, // if wait for notification to end
|
247 | }, function(error, response) {
|
248 | console.log(response);
|
249 | });
|
250 | ```
|
251 |
|
252 | See full usage on the [project homepage:
|
253 | notifu](http://www.paralint.com/projects/notifu/).
|
254 |
|
255 | ### Usage NotifySend
|
256 |
|
257 | Note: notify-send doesn't support the wait flag.
|
258 |
|
259 | ```javascript
|
260 | var NotifySend = require('node-notifier').NotifySend;
|
261 |
|
262 | var notifier = new NotifySend();
|
263 |
|
264 | notifier.notify({
|
265 | title: 'Foo',
|
266 | message: 'Hello World',
|
267 | icon: __dirname + "/coulson.jpg",
|
268 |
|
269 | // .. and other notify-send flags:
|
270 | urgency: void 0,
|
271 | time: void 0,
|
272 | category: void 0,
|
273 | hint: void 0,
|
274 | });
|
275 | ```
|
276 |
|
277 | See flags and options [on the man pages](http://manpages.ubuntu.com/manpages/gutsy/man1/notify-send.1.html)
|
278 |
|
279 | ## CLI
|
280 |
|
281 | You can also use node-notifier as a CLI (as of `v4.2.0`).
|
282 |
|
283 | ```shell
|
284 | $ notify -h
|
285 |
|
286 | # notify
|
287 | ## Options
|
288 | * --help (alias -h)
|
289 | * --title (alias -t)
|
290 | * --subtitle (alias -st)
|
291 | * --message (alias -m)
|
292 | * --icon (alias -i)
|
293 | * --sound (alias -s)
|
294 | * --open (alias -o)
|
295 |
|
296 | ## Example
|
297 |
|
298 | $ notify -t "Hello" -m "My Message" -s --open http://github.com
|
299 | $ notify -t "Agent Coulson" --icon https://raw.githubusercontent.com/mikaelbr/node-notifier/master/example/coulson.jpg -m "Well, that's new. "
|
300 | $ notify -m "My Message" -s Glass
|
301 | $ echo "My Message" | notify -t "Hello"
|
302 | ```
|
303 |
|
304 | You can also pass message in as `stdin`:
|
305 |
|
306 | ```js
|
307 | ➜ echo "Message" | notify
|
308 |
|
309 | # Works with existing arguments
|
310 | ➜ echo "Message" | notify -t "My Title"
|
311 | ➜ echo "Some message" | notify -t "My Title" -s
|
312 | ```
|
313 |
|
314 | ## Thanks to OSS
|
315 |
|
316 | A very special thanks to all the modules `node-notifier` uses.
|
317 | * [terminal-notifier](https://github.com/alloy/terminal-notifier)
|
318 | * [toaster](https://github.com/nels-o/toaster)
|
319 | * [notifu](http://www.paralint.com/projects/notifu/)
|
320 | * [growly](https://github.com/theabraham/growly/)
|
321 |
|
322 | [![NPM downloads][npm-downloads]][npm-url]
|
323 |
|
324 | ## License
|
325 |
|
326 | [MIT License](http://en.wikipedia.org/wiki/MIT_License)
|
327 |
|
328 | [npm-url]: https://npmjs.org/package/node-notifier
|
329 | [npm-image]: http://img.shields.io/npm/v/node-notifier.svg?style=flat
|
330 | [npm-downloads]: http://img.shields.io/npm/dm/node-notifier.svg?style=flat
|
331 |
|
332 | [travis-url]: http://travis-ci.org/mikaelbr/node-notifier
|
333 | [travis-image]: http://img.shields.io/travis/mikaelbr/node-notifier.svg?style=flat
|
334 |
|
335 | [depstat-url]: https://gemnasium.com/mikaelbr/node-notifier
|
336 | [depstat-image]: http://img.shields.io/gemnasium/mikaelbr/node-notifier.svg?style=flat
|