Repository files navigation

notification plugin forgulp

• Information
• Requirements
• Usage
• Notes/tip
• API
  • notify(String)
  • notify(Function)
  • notify(options)
    • options.onLast
    • options.emitError
    • options.message
    • options.title
    • options.templateOptions
    • options.notifier
  • notify.withReporter(Function)
  • notify.onError()
  • notify.logLevel(level)
• Disablegulp-notify
• Examples
  • As jshint reporter
• License

• Mac OS X: No external installation needed (if Mac OS X 10.8 or higher).
• Linux:notify-send/notify-osd should be installed (On Ubuntu this is installed per default)
• Windows: Uses native toaster (if Windows 8 or higher).
• Fallback: Growl: Growl (for Mac, Windows or similar) should be installed.

Seenode-notifier for details.

Windows 10 Note: You might have to activate banner notification for the toast to show.

From#90 (comment)

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)

First, installgulp-notify as a development dependency:

npm install --save-dev gulp-notify

Then, add it to yourgulpfile.js:

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

Or with template

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

Seeexamples for more or theAPI section for various inputs.

gulp-notify passes on thevinyl files even on error. So if you areusinggulp-plumber the runwill not break if the notifier returns an error.

If you want to notify on errorsgulp-plumbercan be used to not break the run and force you to have to restart gulp.

You can usenotify.onError() as the errorHandler for gulp-plumber like this:

gulp.src("../test/fixtures/*").pipe(plumber({errorHandler:notify.onError("Error: <%= error.message %>")})).pipe(through(function(){this.emit("error",newError("Something happend: Error message!"))}));

A message to notify per data on stream.The string can be a lodash template asit is passed throughgulp-util.template.

Type:function(VinylFile)

Vinyl File from gulp stream passed in as argument.

The result of the function can be a string used as the message or an options object (see below).If the returned value is a string, it can be a lodash template asit is passed throughgulp-util.template.

Iffalse is returned from the function the notification won't run.

*Options are passed onto the reporter, so on Windows, you can defineGrowl host, on Mac you can pass in contentImage, and so on.

Seenode-notifierfor all options*

Default notification values:

• Gulp logo on regular notification
• Inverted Gulp logo on error
• Frog sound on error on Mac.

See also theadvanced example.

Type:BooleanDefault:false

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

Type:BooleanDefault:false

If the returned stream should emit an error or not.IfemitError is true, you have to handle.on('error')manually in case the notifier (gulp-notify) fails. Ifthe defaultfalse is set, the error will not be emittedbut simply printed to the console.

This means you can run the notifier on a CI system withoutopting it out but simply letting it fail gracefully.

Type:StringDefault: File path in stream

The message you wish to attach to file. The string can be alodash template as it is passed throughgulp-util.template.

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

Type:Function(vinylFile)

Seenotify(Function).

Type:StringDefault: "Gulp Notification"

The title of the notification. The string can be alodash template as it is passed throughgulp-util.template.

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

Type:Function(vinylFile)

Seenotify(Function).

Type:ObjectDefault: {}

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

Examples:

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

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. Optionswill contain both title and message.

Seenotify.withReporter for syntactic sugar.

If thewait option is set totrue, the notifier will triggereventsclick ortimeout, whether the user clicks the notification or ittimes out. You listen to these events on the main notify object, not theproduces stream.

varnotify=require('gulp-notify');notify.on('click',function(options){console.log('I clicked something!',options);});notify.on('timeout',function(options){console.log('The notification timed out',options);});gulp.task("click",function(){returngulp.src("some/glob/**").pipe(notify({message:'Click or wait',wait:true}));});

Type:Reporter

Wrapsoptions.notifier to return a new notify-function only usingthe passed in reporter.

Example:

varcustom=notify.withReporter(function(options,callback){console.log("Title:",options.title);console.log("Message:",options.message);callback();});gulp.src("../test/fixtures/1.txt").pipe(custom("This is a message."));

This will be the same as

gulp.src("../test/fixtures/1.txt").pipe(notify({message:"This is a message."notifier:function(options,callback){console.log("Title:",options.title);console.log("Message:",options.message);callback();}}));

But much, much prettier.

The exact same API as usingnotify(), but where avinyl Fileis passed, the error object is passed instead.

Example:

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

Or simply:

gulp.src("../test/fixtures/*").pipe(through(function(){this.emit("error",newError("Something happend: Error message!"))})).on("error",notify.onError("Error: <%= error.message %>"));

gulp.src("../test/fixtures/*").pipe(through(function(){this.emit("error",newError("Something happend: Error message!"))})).on("error",notify.onError({message:"Error: <%= error.message %>",title:"Error running something"}));

TheonError() end point does supportlodash.template.

onError() will automatically end the stream for you. Making it easer for watching.

Type:IntegerDefault:2

Set if logger should be used or not. If log level is set to 0,no logging will be used. If no new log level is passed, thecurrent log level is returned.

• 0: No logging
• 1: Log on error
• 2: Log both on error and regular notification.

If logging is set to> 0, the title andmessage passed togulp-notify will be logged like so:

➜  gulp-notify git:(master) ✗ gulp --gulpfile examples/gulpfile.js one[gulp] Using file /Users/example/gulp-notify/examples/gulpfile.js[gulp] Working directory changed to /Users/example/repos/gulp-notify/examples[gulp] Running'one'...[gulp] Finished'one'in 4.08 ms[gulp] gulp-notify: [Gulp notification] /Users/example/gulp-notify/test/fixtures/1.txt

If you are running on a system that handles notifications poorly or you simplydo not wish to usegulp-notify but your project does? You can disablegulp-notifyby using enviroment variableDISABLE_NOTIFIER.

export DISABLE_NOTIFIER=true;

This will disable all methods;notify(),notify.onError andnotify.withReporter.

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] Tasksfor /Users/example/gulp-notify/examples/gulpfile.js[gulp] ├── multiple[gulp] ├── one[gulp] ├── message[gulp] ├── customReporter[gulp] ├── template[gulp] ├── templateadv[gulp] ├── function[gulp] ├── onlast[gulp] ├── advanceMac[gulp] ├── error[gulp] ├── forceGrowl[gulp] └── customError

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

gulp-notify can easily be used as jshint reporter.As jshint exposes the result on the vinyl file we canuse them in a function like so:

gulp.task('lint',function(){gulp.src('/src/**/*.js').pipe(jshint())// Use gulp-notify as jshint reporter.pipe(notify(function(file){if(file.jshint.success){// Don't show something if successreturnfalse;}varerrors=file.jshint.results.map(function(data){if(data.error){return"("+data.error.line+':'+data.error.character+') '+data.error.reason;}}).join("\n");returnfile.relative+" ("+file.jshint.results.length+" errors)\n"+errors;}));});

If you use a function for message ingulp-notify, the message won't be shown.This is true for both direct use of function and{ message: function () {}}.

MIT License