gulp-notify

gulp-notify

notification plugin for gulp

Information

Package	gulp-notify
Description	Send messages to Mac Notification Center or Linux notifications (using notify-send) using the node-notifier module. Can also specify custom notifier (e.g. Growl notification).
Node Version	>= 0.8

Note: Without overriding the notifier, Mac OS X >= 10.8 or as of v0.3.2, Linux with notify-send installaed is required for this to run.

Usage

First, install gulp-notify as a development dependency:

npm install --save-dev gulp-notify

Then, add it to your gulpfile.js:

var notify = require("gulp-notify");
gulp.src("./src/test.ext")
  .pipe(notify("Hello Gulp!"));

Or with template

var notify = require("gulp-notify");
gulp.src("./src/test.ext")
  .pipe(notify("Found file: <%= file.relative %>!"));

See examples for more og the API section for various inputs.

API

notify(String)

A message to notify per data on stream. The string can be a lodash template as it is passed through gulp-util.template.

notify(Function)

Type: function(VinylFile)

The result of the function is used as message. Vinyl File from gulp stream passed in as argument.

The returned string can be a lodash template as it is passed through gulp-util.template.

notify(options)

options.onLast

Type: Boolean
Default: false

If the notification should only happen on the last file of the stream. Per default a notification is triggered on each file.

options.message

Type: String
Default: File path in stream

The message you wish to attach to file. The string can be a lodash template as it is passed through gulp-util.template.

Example: Created <%= file.relative %>.

as function

Type: Function(vinylFile)

See notify(Function).

options.title

Type: String
Default: "Gulp Notification"

The title of the notification. The string can be a lodash template as it is passed through gulp-util.template.

Example: Created <%= file.relative %>.

as function

Type: Function(vinylFile)

See notify(Function).

options.templateOptions

Type: Object
Default: {}

Object passed to the lodash template, for additional properties passed to the template.

Examples:

gulp.src("../test/fixtures/*")
    .pipe(notify({
      message: "Generated file: <%= file.relative %> @ <%= options.date %>",
      templateOptions: {
        date: new Date()
      }
    }))

options.notifier

Type: Function(options, callback)
Default: node-notifier module

Swap out the notifier by passing in an function. The function expects two arguments: options and callback.

The callback must be called when the notification is finished. Options will contain both title and message.

notify.onError()

Same API as using notify(), but instead of being passed vinyl File an error object gets sent.

Example:

gulp.src("../test/fixtures/*")
      .pipe(through(function () {
        this.emit("error", "Something happend: Error message!")
      }))
      .on("error", notify.onError(function (error) {
        return "Message to the notifier: " + error.message;
      }));

The onError() end point does not support lodash.template.

Examples

To see all examples run from root:

$ gulp --gulpfile examples/gulpfile.js --tasks
[gulp] Using file /Users/example/gulp-notify/examples/gulpfile.js
[gulp] Working directory changed to /Users/example/gulp-notify/examples
[gulp] Tasks for /Users/example/gulp-notify/examples/gulpfile.js
[gulp] ├── multiple
[gulp] ├── one
[gulp] ├── message
[gulp] ├── function
[gulp] ├── onlast
[gulp] └── error

To run an example:

$ gulp --gulpfile examples/gulpfile.js multiple
[gulp] Using file /Users/example/gulp-notify/examples/gulpfile.js
[gulp] Working directory changed to /Users/example/gulp-notify/examples
[gulp] Running 'multiple'...
[gulp] Finished 'multiple' in 3.75 ms

License

MIT License