Gulp Notify is a notification plugin for Gulp that sends desktop notifications about build status, errors, and completion across multiple platforms (Mac OS X, Linux, Windows). It integrates with the Gulp streaming build system to provide real-time feedback using the node-notifier module with fallbacks to Growl or console logging.
npm install --save-dev gulp-notifyconst notify = require("gulp-notify");For ES modules (where supported):
import notify from "gulp-notify";const gulp = require("gulp");
const notify = require("gulp-notify");
// Simple notification
gulp.src("./src/**/*.js")
.pipe(notify("Hello Gulp!"));
// Template notification
gulp.src("./src/**/*.js")
.pipe(notify("Found file: <%= file.relative %>!"));
// Error handling
gulp.src("./src/**/*.js")
.pipe(someTask())
.on("error", notify.onError("Error: <%= error.message %>"));Creates a gulp transform stream that sends notifications for each file processed.
/**
* Creates a notification stream for Gulp pipelines
* @param options - Notification options (string, function, or object)
* @returns Transform stream
*/
function notify(options?: string | Function | NotifyOptions): Transform;
interface NotifyOptions {
/** Notification message or template string */
message?: string | Function;
/** Notification title or template string */
title?: string | Function;
/** Notification subtitle (macOS only) */
subtitle?: string | Function;
/** Path to notification icon */
icon?: string;
/** Notification sound name or false to disable */
sound?: string | boolean;
/** Only notify on the last file in stream */
onLast?: boolean;
/** Emit errors instead of logging them */
emitError?: boolean;
/** Custom notification function */
notifier?: Function;
/** Variables for template interpolation */
templateOptions?: object;
/** Host for remote notifications */
host?: string;
/** Application name for remote notifications */
appName?: string;
/** Port for remote notifications */
port?: string | number;
/** URL or application to open on click */
open?: string | Function;
}Usage Examples:
// String message
gulp.src("./src/*.js")
.pipe(notify("Build complete!"));
// Template message
gulp.src("./src/*.js")
.pipe(notify("Processed: <%= file.relative %>"));
// Function message
gulp.src("./src/*.js")
.pipe(notify(function(file) {
return "Processed: " + file.relative;
}));
// Full options
gulp.src("./src/*.js")
.pipe(notify({
title: "Build Status",
message: "Processed <%= file.relative %>",
icon: path.join(__dirname, "build-icon.png"),
sound: "Blow",
onLast: true
}));Creates an error handler function for gulp stream error events.
/**
* Creates an error handler for gulp stream errors
* @param options - Error notification options
* @param callback - Optional callback function
* @returns Error handler function
*/
function onError(options?: string | Function | NotifyOptions, callback?: Function): Function;Usage Examples:
// Simple error message
gulp.src("./src/*.js")
.pipe(someTask())
.on("error", notify.onError("Build failed!"));
// Template error message
gulp.src("./src/*.js")
.pipe(someTask())
.on("error", notify.onError("Error: <%= error.message %>"));
// Full error options
gulp.src("./src/*.js")
.pipe(someTask())
.on("error", notify.onError({
title: "Build Error",
message: "Task failed: <%= error.message %>",
sound: "Frog",
icon: path.join(__dirname, "error-icon.png")
}));
// With callback
gulp.src("./src/*.js")
.pipe(someTask())
.on("error", notify.onError({
message: "Error: <%= error.message %>"
}, function(err) {
console.log("Notification sent for error:", err.message);
}));Creates a notify function with a custom notification reporter.
/**
* Creates a notify function with custom reporter
* @param reporter - Custom notification function
* @returns Configured notify function with onError, logLevel, logger methods
*/
function withReporter(reporter: Function): CustomNotify;
interface CustomNotify {
/** Creates notification stream with custom reporter */
(options?: string | Function | NotifyOptions): Transform;
/** Creates error handler with custom reporter */
onError(options?: string | Function | NotifyOptions): Function;
/** Gets or sets log level */
logLevel(level?: number): number | void;
/** Gets or sets logger function */
logger(logger?: Function): Function | void;
}
/**
* Custom reporter function signature
* @param options - Notification options to display
* @param callback - Callback to call when notification is complete
*/
type Reporter = (options: ReporterOptions, callback: Function) => void;
interface ReporterOptions {
title: string;
message: string;
subtitle?: string;
icon?: string;
sound?: string | boolean;
open?: string;
[key: string]: any;
}Usage Examples:
// Console reporter
const consoleNotify = notify.withReporter(function(options, callback) {
console.log("Title:", options.title);
console.log("Message:", options.message);
callback();
});
gulp.src("./src/*.js")
.pipe(consoleNotify("Build complete!"));
// Custom Growl reporter
const growlNotify = notify.withReporter(function(options, callback) {
const growl = require("node-notifier").Growl;
new growl().notify(options, callback);
});
gulp.src("./src/*.js")
.on("error", growlNotify.onError("Error: <%= error.message %>"));Controls the logging level and logger function for internal notifications.
/**
* Gets or sets the logging level
* @param level - Log level (0=none, 1=errors only, 2=all)
* @returns Current log level if no parameter provided
*/
function logLevel(level?: number): number | void;
/**
* Gets or sets the logger function
* @param logger - Custom logger function
* @returns Current logger if no parameter provided
*/
function logger(logger?: Function): Function | void;Usage Examples:
// Set log level
notify.logLevel(1); // Only log errors
notify.logLevel(0); // Disable all logging
notify.logLevel(2); // Log everything (default)
// Custom logger
notify.logger(function(message) {
console.log("[NOTIFY]", message);
});
// Get current settings
const currentLevel = notify.logLevel();
const currentLogger = notify.logger();Registers event listeners on the underlying notifier for click events.
/**
* Registers event listeners on the notifier
* @param event - Event name (e.g., 'click')
* @param fn - Event handler function
* @returns Result of notifier.on()
*/
function on(event: string, fn: Function): any;Usage Examples:
// Handle notification clicks
notify.on('click', function(options) {
console.log('Notification clicked!', options);
});
// Click-enabled notification
gulp.src("./src/*.js")
.pipe(notify({
message: "Build complete!",
wait: true, // Required for click events
open: "http://localhost:3000"
}));Notifications support Lodash template syntax for dynamic content.
interface TemplateContext {
/** Available for regular notifications */
file?: {
/** Relative file path */
relative: string;
/** Full file path */
path: string;
/** File base directory */
base: string;
/** File current working directory */
cwd: string;
};
/** Available for error notifications */
error?: {
/** Error message */
message: string;
/** Error name/type */
name: string;
/** Error stack trace */
stack: string;
};
/** Custom template options */
options?: object;
}Template Examples:
// File templates
notify("Processing: <%= file.relative %>");
notify("Full path: <%= file.path %>");
// Error templates
notify.onError("Error in <%= file.relative %>: <%= error.message %>");
// Custom template options
notify({
message: "Build <%= options.env %> complete!",
templateOptions: { env: "production" }
});
// Function-based templates
notify({
title: function(file) {
return file.isNull() ? "Folder:" : "File: " + file.relative;
},
message: "Custom message for <%= file.relative %>"
});// Environment variable to disable all notifications
process.env.DISABLE_NOTIFIER = "true";When DISABLE_NOTIFIER is set, all notification functions become no-ops.
const plumber = require("gulp-plumber");
gulp.src("./src/*.js")
.pipe(plumber({
errorHandler: notify.onError("Error: <%= error.message %>")
}))
.pipe(someTask());// Emit errors to stop pipeline
gulp.src("./src/*.js")
.pipe(notify({
message: "Processing...",
emitError: true
}))
.on("error", function(err) {
console.log("Pipeline stopped:", err);
});// Send notifications to remote host
gulp.src("./src/*.js")
.pipe(notify({
message: "Remote build complete!",
host: "remote.server.com",
port: 23053,
appName: "MyApp Build"
}));// Only notify on last file
gulp.src("./src/**/*.js")
.pipe(notify({
onLast: true,
message: function(file) {
return "Processed " + file.relative + " (last file)";
}
}));
// Conditional notification based on file
gulp.src("./src/**/*.js")
.pipe(notify(function(file) {
if (file.relative.includes("important")) {
return "Important file processed: " + file.relative;
}
return false; // No notification
}));