Thursday, 20 September 2018

Introduction to Gulp


What is Gulp?


Gulp is a:

  • toolkit for automating & enhancing JavaScript development workflow
  • Node.js based build system
  • JavaScript task runner which can automate common tasks (e.g. minification, error checking, bundling etc...)

How to install Gulp?


Two packages have to be installed: CLI and the core one.

CLI package has to be installed globally:

> npm install --global gulp-cli

The local installation guarantees that the project build will not break even if system install is upgraded. The global gulp install (CLI) is there only to provide a binary command in the path. Gulp is designed in a way that a specific project can depend on a specific version of the build system so it will still build no matter the state or installed version of the global package.

How to check if gulp CLI is installed?

C:\dev\github\gulp-demo>npm list -g gulp-cli
C:\Users\user\AppData\Roaming\npm
`-- gulp-cli@2.0.1

Gulp core package has to be installed locally. To check if it's already been installed we can use:

C:\dev\github\gulp-demo>npm list gulp
gulp-demo@1.0.0 C:\dev\github\gulp-demo
`-- (empty)

Let's install it (but if package.json hasn't been created yet, execute npm init):

C:\dev\github\gulp-demo>npm install --save-dev gulp
npm WARN deprecated gulp-util@3.0.8: gulp-util is deprecated - replace it, following the guidelines at https://medium.com/gulpjs/gulp-util-ca3b1f9f9ac5
npm WARN deprecated graceful-fs@3.0.11: please upgrade to graceful-fs 4 for compatibility with current and future versions of Node.js
npm WARN deprecated minimatch@2.0.10: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated minimatch@0.2.14: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated graceful-fs@1.2.3: please upgrade to graceful-fs 4 for compatibility with current and future versions of Node.js
npm notice created a lockfile as package-lock.json. You should commit this file.
+ gulp@3.9.1
added 253 packages from 162 contributors and audited 1112 packages in 9.569s
found 5 vulnerabilities (1 low, 4 high)
  run `npm audit fix` to fix them, or `npm audit` for details

Let's verify installation:

C:\dev\github\gulp-demo>npm list gulp
gulp-demo@1.0.0 C:\dev\github\gulp-demo
`-- gulp@3.9.1

gulp package does not represent Gulp's latest version. [read here and here]
In order to get the latest version we should use gulp@next.

So let's uninstall version 3.9.1 and install the latest Gulp:

C:\dev\github\gulp-demo>npm uninstall gulp
removed 253 packages in 3.447s
found 0 vulnerabilities

C:\dev\github\gulp-demo>npm install --save-dev gulp@next
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.4 (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.4: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

+ gulp@4.0.0
added 318 packages from 212 contributors and audited 5472 packages in 15.089s
found 0 vulnerabilities

How to check Gulp version?


C:\dev\github\gulp-demo>gulp -v
[13:49:01] CLI version 2.0.1
[13:49:01] Local version 4.0.0

How to configure Gulp?


Let's try to run gulp now:

\gulp-demo>gulp
[13:49:32] No gulpfile found

Gulp requires a gulpfile.js file at the root of the project. Gulpfile contains tasks it can run from the command line. Let's define a default task which prints Hello world! to the console:

\gulp-demo\gulpfile.js:

var gulp = require('gulp');

gulp.task('default', function() {
  // place code for your default task here
  console.log('Hello, world!');
});

When we run gulp with no arguments, it will run the task named as default:

C:\dev\github\gulp-demo>gulp
[13:55:13] Using gulpfile C:\dev\github\gulp-demo\gulpfile.js
[13:55:13] Starting 'default'...
Hello, world!
[13:55:13] The following tasks did not complete: default
[13:55:13] Did you forget to signal async completion?

We could have explicitly named the task we want to run:

C:\dev\github\gulp-demo>gulp default
[13:55:24] Using gulpfile C:\dev\github\gulp-demo\gulpfile.js
[13:55:24] Starting 'default'...
Hello, world!
[13:55:24] The following tasks did not complete: default
[13:55:24] Did you forget to signal async completion?

Gulp CLI


These are the Gulp CLI command line arguments:
>gulp --help

Usage: gulp [options] tasks

Options:
  --help, -h              Show this help.                              [boolean]
  --version, -v           Print the global and local gulp versions.    [boolean]
  --require               Will require a module before running the gulpfile.
                          This is useful for transpilers but also has other
                          applications.                                 [string]
  --gulpfile, -f          Manually set path of gulpfile. Useful if you have
                          multiple gulpfiles. This will set the CWD to the
                          gulpfile directory as well.                   [string]
  --cwd                   Manually set the CWD. The search for the gulpfile, as
                          well as the relativity of all requires will be from
                          here.                                         [string]
  --verify                Will verify plugins referenced in project's
                          package.json against the plugins blacklist.
  --tasks, -T             Print the task dependency tree for the loaded
                          gulpfile.                                    [boolean]
  --tasks-simple          Print a plaintext list of tasks for the loaded
                          gulpfile.                                    [boolean]
  --tasks-json            Print the task dependency tree, in JSON format, for
                          the loaded gulpfile.
  --tasks-depth, --depth  Specify the depth of the task dependency tree.[number]
  --compact-tasks         Reduce the output of task dependency tree by printing
                          only top tasks and their child tasks.        [boolean]
  --sort-tasks            Will sort top tasks of task dependency tree. [boolean]
  --color                 Will force gulp and gulp plugins to display colors,
                          even when no color support is detected.      [boolean]
  --no-color              Will force gulp and gulp plugins to not display
                          colors, even when color support is detected. [boolean]
  --silent, -S            Suppress all gulp logging.                   [boolean]
  --continue              Continue execution of tasks upon failure.    [boolean]
  --series                Run tasks given on the CLI in series (the default is
                          parallel).                                   [boolean]
  --log-level, -L         Set the loglevel. -L for least verbose and -LLLL for
                          most verbose. -LLL is default.                 [count]

--tasks
Lists all tasks defined in gulpfile.
Example:

>gulp  --tasks
[17:11:17] Tasks for C:\dev\gulp-demo\gulpfile.js
[17:11:17] ├── build_brandA_environmentA
[17:11:17] ├─┬ pack_brandA_environmentA
[17:11:17] │ └─┬ <series>
[17:11:17] │   ├── build_brandA_environmentA
[17:11:17] │   └── <anonymous>
[17:11:17] ├── build_brandB_environmentA
[17:11:17] ├─┬ pack_brandB_environmentA
[17:11:17] │ └─┬ <series>
[17:11:17] │   ├── build_brandB_environmentA
[17:11:17] │   └── <anonymous>
[17:11:17] ├─┬ build
[17:11:17] │ └─┬ <parallel>
[17:11:17] │   ├── build_brandA_environmentA
[17:11:17] │   └── build_brandB_environmentA
[17:11:17] ├─┬ pack
[17:11:17] │ └─┬ <parallel>
[17:11:17] │   ├─┬ pack_brandA_environmentA
[17:11:17] │   │ └─┬ <series>
[17:11:17] │   │   ├── build_brandA_environmentA
[17:11:17] │   │   └── <anonymous>
[17:11:17] │   └─┬ pack_brandB_environmentA
[17:11:17] │     └─┬ <series>
[17:11:17] │       ├── build_brandB_environmentA
[17:11:17] │       └── <anonymous>
[17:11:17] ├─┬ watch
[17:11:17] │ └─┬ <series>
[17:11:17] │   ├─┬ build
[17:11:17] │   │ └─┬ <parallel>
[17:11:17] │   │   ├── build_brandA_environmentA
[17:11:17] │   │   └── build_brandB_environmentA
[17:11:17] │   └── watch
[17:11:17] ├─┬ default
[17:11:17] │ └─┬ <series>
[17:11:17] │   └─┬ build
[17:11:17] │     └─┬ <parallel>
[17:11:17] │       ├── build_brandA_environmentA
[17:11:17] │       └── build_brandB_environmentA
[17:11:17] └── help

Gulp API


All function arguments can take arbitrary arguments.

gulp.task


Objective:
   define a task
Format:
   gulp.task(task_name, function () {...})
   gulp.task(task_name,  gulp.series(task1_name, gulp.parallel(task2_name, task3_name)))
   ...

gulp.series


Objective:
   Define which tasks or task and a function have to be executed in serial fashion (one after another). [source]
Format:
   gulp.series(task1_name, task2_name)
   gulp.series(task1_name, function() {...})
   gulp.series(task1_name, gulp.parallel(task2_name, task3_name))
   ...

gulp.parallel


Objective:
   Define which tasks or task and a function have to be executed in parallel. [source]
Format:
   gulp.parallel(task1_name, task2_name)
   gulp.parallel(task1_name, function() {...})
   ...


gulp.watch


Objective:
   Define a function or task(s) to be executed each time any of files that matches the provided pattern change.
Format:
   gulp.watch(file_matching_pattern, function(){...})
   gulp.watch(file_matching_pattern, gulp.series(task1_name, task2_name))
   gulp.watch(file_matching_pattern, gulp.parallel(task1_name, task2_name))
   ...

How is Gulp actually used in projects?


Projects are usually npm-based so contain packages.json. Its "scripts" section contains one or more scripts which are basically executions of Gulp tasks (in form gulp [options] tasks). Gulp tasks are defined in gulpfile.js. Gulp is indirectly executed via npm.

Further reading:

Gulp - Getting Started
Gulp js interview questions for beginners
Gulp recipes
How do I update to Gulp 4?
A quick guide for switching to gulp 4

No comments: