gulp-watch

What is gulp-watch?

The gulp-watch package is a file watcher that is used in conjunction with Gulp, a popular build system for automating tasks in web development. It allows developers to watch files and directories for changes and execute tasks automatically when changes are detected.

What are gulp-watch's main functionalities?

Watch Files for Changes

This feature allows you to watch JavaScript files in the 'src' directory and its subdirectories. When any of these files change, the 'scripts' task is automatically executed.

const gulp = require('gulp');
const watch = require('gulp-watch');

watch('src/**/*.js', function() {
  gulp.start('scripts');
});

Watch with Options

This feature demonstrates how to use options with gulp-watch. The 'ignoreInitial' option is set to false, meaning the 'styles' task will run immediately when the watch starts, as well as on subsequent changes.

const gulp = require('gulp');
const watch = require('gulp-watch');

watch('src/**/*.css', { ignoreInitial: false }, function() {
  gulp.start('styles');
});

Watch Multiple File Types

This feature shows how to watch multiple types of files. Both JavaScript and CSS files in the 'src' directory are watched, and the 'build' task is executed when any of these files change.

const gulp = require('gulp');
const watch = require('gulp-watch');

watch(['src/**/*.js', 'src/**/*.css'], function() {
  gulp.start('build');
});

Other packages similar to gulp-watch

chokidar

Chokidar is a fast and efficient file watcher for Node.js. It is a lower-level library compared to gulp-watch and can be used independently of Gulp. Chokidar provides more granular control over file watching and is known for its performance and reliability.

gulp

Gulp itself has a built-in watch method that can be used to watch files and execute tasks. While gulp-watch offers more features and flexibility, the built-in watch method is simpler and sufficient for many use cases.

nodemon

Nodemon is a tool that automatically restarts a Node.js application when file changes are detected. While it is not a direct replacement for gulp-watch, it serves a similar purpose in the context of Node.js applications by automating the restart process during development.

README

gulp-watch

File watcher that uses super-fast chokidar and emits vinyl objects.

Installation

npm install --save-dev gulp-watch

Usage

var gulp = require('gulp'),
    watch = require('gulp-watch');

gulp.task('stream', function () {
	// Endless stream mode
    return watch('css/**/*.css', { ignoreInitial: false })
        .pipe(gulp.dest('build'));
});

gulp.task('callback', function () {
	// Callback mode, useful if any plugin in the pipeline depends on the `end`/`flush` event
    return watch('css/**/*.css', function () {
        gulp.src('css/**/*.css')
            .pipe(gulp.dest('build'));
    });
});

Protip: until gulpjs 4.0 is released, you can use gulp-plumber to prevent stops on errors.

More examples can be found in docs/readme.md.

API

watch(glob, [options, callback])

Creates a watcher that will spy on files that are matched by glob which can be a glob string or array of glob strings.

Returns a pass through stream that will emit vinyl files (with additional event property) that corresponds to event on file-system.

Callback function(vinyl)

This function is called when events happen on the file-system. All incoming files that are piped in are grouped and passed to the events stream as is.

• vinyl — is vinyl object that corresponds to the file that caused the event. Additional event field is added to determine what caused changes.

Possible events:

• add - file was added to watch or created
• change - file was changed
• unlink - file was deleted

Options

This object is passed to the chokidar options directly. Options for gulp.src are also available. If you do not want content from watch, then add read: false to the options object.

options.ignoreInitial

Type: Boolean
Default: true

Indicates whether chokidar should ignore the initial add events or not.

options.events

Type: Array
Default: ['add', 'change', 'unlink']

List of events, that should be watched by gulp-watch. Contains event names from chokidar.

options.base

Type: String
Default: undefined

Use explicit base path for files from glob. Read more about base and cwd in gulpjs docs.

options.name

Type: String
Default: undefined

Name of the watcher. If it is present in options, you will get more readable output.

options.verbose

Type: Boolean
Default: false

This option will enable verbose output.

options.readDelay

Type: Number
Default: 10

Wait for readDelay milliseconds before reading the file.

options.read

Type: Boolean
Default: true

Setting this to false will return file.contents as null and not read the file at all. Most useful as an optimization if your plugins pipeline doesn't make use of the file contents (e.g. gulp-clean), or to avoid reading the file twice if you use gulp.src() inside the callback instead of the file object that is passed as argument.

Methods

Returned Stream from constructor has some useful methods:

• add(path / paths)
• unwatch(path / paths)
• close()

Events

All events from chokidar:

• add, change, unlink, addDir, unlinkDir, error, ready, raw

Changelog

License

MIT (c) 2014 Vsevolod Strukchinsky ([e-mail])