Gulp 4

Check Gulp version
Install old version of Gulp
How to organize files
SASS with Gulp
Gulp and PostCSS
Common Errors
did you forget to signal async completion?
Related Articles


Gulp is a task manager for automatically performing frequently used tasks. (e.g. minification, testing, file combining) written in JavaScript programming language.

Software uses command line to run tasks defined in the Gulpfile.js .

Created as an offshoot of the Grunt project to take best practices from it.

Gulp is distributed through NPM package manager under MIT license.

If you copy the code from this page - keep in mind that I put in some places extra spaces - solely to improve readability on some screens. Feel free to delete them.

This is the main article about using Gulp. At the moment, you can also read articles in addition to this:

How to copy a folder using Gulp
How to send files via ftp using Gulp
Gulp series
Processing only modified files with'change')


Consider installing using npm .

In the follwing manual it is assumed that you have already installed nmp.

Check how to install npm in my article Installing npm

About how to install an older version of Gulp - Install an archive version of Gulp

$ npm install gulp-cli --global

Roaming\npm\gulp ->


+ gulp-cli@2.2.0

updated 7 packages in 7.386s

Check Gulp version

To check Gulp version execute

gulp -v

CLI version: 2.2.0
Local version: Unknown

About installing not the latest, but some specific version of Gulp read here

Now you need to go to the directory in which you plan to work. I will make the site so I go to the directory

$ cd /c/Users/ao/Desktop/

Then go directly to installing gulp in the current project

$ npm install gulp --save-dev

By adding the --save-dev switch, we indicated that we now save to the dev branch, since Gulp this is a package that we will use in development, but put it on hosting we won’t, as he will not do anything on the site. All gulp work will be on developer side.

Read more

Let's see how our pacakge.json file has changed

vi package.json

{ "name": "heihei", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "author": "", "license": "ISC", "dependencies": { "jquery": "^3.4.1", "normalize.css": "^8.0.1" }, "devDependencies": { "gulp": "^4.0.2" }, "repository": { "type": "git", "url": "git+" }, "bugs": { "url": "" }, "homepage": "" }

The devDependencies section has appeared, in which in the future I will add quite a lot of packages.

If you now see the contents of the node_modules folder you can see that the Gulp installation has added more than one folder, such as I would make jquery and a few dozen.

Old versions npm always created one folder and placed all the dependencies there.

Newer versions of npm save dependencies in the parent folder node_modules.

Install an older version

Sometimes it is necessary to install not the current, but an earlier version of Gulp.

This is especially true for version 3.9.1, which is very different from 4 and above.

You can do this by adding the correct version after @

npm install gulp@3.9.1 --save-dev

npm install gulp-cli@1.2.1 --save-dev

The Gulp version list is here , Gulp-cli - here . You need to open the Versions tab

If you want to first uninstall your version of Gulp and only then install another one - do this can be done with the uninstall command

npm uninstall gulp


After installing Gulp, you need to in the root directory of the project (in my case - heiheiru) create file gulpfile.js in which we will write down instructions for Gulp.

The first thing we write down there

const gulp = require('gulp');

Starting with version 4.0, you can use the new JavaScript syntax (ES2015+)

import gulp from 'gulp'

But for this you need to install babel and make sure that there are no errors. I saw complaints on the forums myself have not tried it yet.


After the gulpfile.js file has been created can run gulp


The result will be a similar message

[11:22:35] Using gulpfile ~\Desktop\Sites\

[11:22:35] Task never defined: default

[11:22:35] To list available tasks, try running: gulp --tasks

Gulp complains that the default task is not defined - default task

Need to define it

vi gulpfile.js

const gulp = require('gulp'); gulp.task('default', function() { console.log("Gulp is running!"); });


default will start but now Gulp will complain about an incomprehensible closure.

[11:31:44] Using gulpfile ~\Desktop\Sites\heihei\gulpfile.js [11:31:44] Starting 'default'... Gulp is running! [11:31:44] The following tasks did not complete: default [11:31:44] Did you forget to signal async completion?

This error can be fixed in several ways. ways . I use the following:

const gulp = require('gulp'); gulp.task('default', function(cb) { console.log("Gulp is running!"); cb() });


File organization

In order not to create mess from files and directories, we need to organize everything right from the very beginning.

Root directroy should have easy to understand name. Typically it is the name of your project. In this example it can be heihei or heiheiru

In this folder we need to initialize GIT and npm.

npm will create a directory called node_modules

It will also create the following files: package.json and package-lock.json .

It is also a good moment to create a .gitignore file.

We are using Gulp which means that there will be a gulpfile.js

With the growing number of tasks that Gulp will perform, it will become inconvenient for us to store them all in one file.

In gulpfile.js we will only import other .js files according to the principle - for each job one file.

To store these files we will need a folder, let's call it gulp and create it in the root. Inside it, create Tasks subfolder

All that relates directly to the site put in a folder heiheiru/app

index.html will put to the root app and .css files, pictures and scripts we put into following directories


This will look like a folder tree in the editor Sublime

How to organize directories for Gulp project image form

Gulp Usecases

A simple example is a task that recursively copies a folder and writing logs.

This case is explained in the «How to copy a folder using Gulp» article.

More complex example - «How to send files via ftp using Gulp»

Processing Style Files

Metalanguages like SASS can save a lot of time by reducing manual work.

Install it using npm

npm install gulp-sass --save-dev

Now you can declare a sass variable and use this preprocessor

const gulp = require('gulp'); const sass = require('gulp-sass'); const browserSync = require( 'browser-sync' ).create(); gulp.task('default', function(done) { console.log("Gulp is running!"); done(); }); // compile scss into css function style() { // 1. show the location .scss файлов return gulp.src('./scss/**/*.scss') // 2. passing them through sass compiller .pipe(sass()) // 3. specify the CSS file into which the result is written .pipe(gulp.dest( './css/style.css' ) ) } = style;

const and let - have been introduced in JavaScript since ES6 and for modern JavaScript are a better option than var


gulp-watch is the name of a Gulp plugin that tracks file changes. Starting from the fourth Gulp version gulp-watch is included in the main package and does not require separate installation.

Let's start with a simple one - we make a function that each time the index.html file is changed to The app folder will display a warning.

What it looks like in Gulp 4

// include gulp // no need to include gulp-watch separately // it is included to Gulp starting from version 4 const gulp = require('gulp'); // function that will log all changes function html() { console.log("index.html was edited!"); } // function that monitors index.html // you can name it watch, but for this time // I prefer watchFiles // you will see the reason later when we do exports function watchFiles() { "./app/assets/index.html", html); } // To call our functions from the outside, // e.g. from GitBash we write exports // To the left we write name that we want to use outside, // To the right there are our functions local names exports.html = html; = watchFiles;

To start monitoring write

gulp watch

[20:12:19] Using gulpfile ~\Desktop\Sites\heihei\gulpfile.js
[20:12:19] Starting 'watch'...

Change something in index.html and save

[20:14:28] Starting 'html'...
Someone edited index.html!

In Gulp 3 it used to look like this:

// Importing gulp и gulp-watch const gulp = require('gulp') watch = require('gulp-watch'); gulp.task('html', function() { console.log( "Someone edited index.html!"); } gulp.task('watch', function() { watch( './app/assets/index.html', function() { gulp.start('html'); }); });

Create a directory


To keep all .css filsed for development

We will write a function that will collect all the .css files from this folder, process them using sass, and merge them into a single file. Someone has edited. Someone has edited. /app/temp/styles/style.css

We already wrote such a function above, just change it a little.

Add .css file monitoring"./app/assets/styles/**/*.css", style);

function style() { console.log("style is running!"); // 1. return gulp.src("./app/assets/styles/*.css" ) // 2. pass that file through sass compiller .pipe(sass()) // 3. where do I save the compiled CSS? .pipe( gulp.dest( './app/temp/styles/style.css' ) ) } function watchFiles() {"./app/assets/index.html", html);"./app/assets/styles/**/*.css", style); }

Now, as soon as we edit one of the styles files, watch will notice this change, pass it through sass, and collect all the files into one.

Why do we need SASS:

to use css variables. Create a variable, which then embed in .css pass through sass compiler and when suddenly you need to be everywhere change the value of this variable, for example, the main color will change on the site, everything what we will need to do is change one variable in one file.

to do style attachments (nested css)

to use mixins


Previously, you already read about the SASS preprocessor, which along with LESS and Stylus is the standard for many projects.

I do not use them, but prefer the more modern PostCSS, which has a more modular structure, and accordingly more flexible and quick

Whatever pre or post processor you choose, you need to master working with it, learn perform simple tasks and move on to more complex tasks such as'change')

More details about PostCSS I put to PostCSS article.

You can read about PostCSS and return to this article or to one of the following, more advanced chapters.

I did not post a description of working with PostCSS here, because it can be run not just using gulp

Gulp Video Tutorials

Videos weigh a lot, so I dedicated a separate page for them - Gulp Video Tutorials



Error installing gulp. You perform

$ npm install gulp --save-dev

And in return you have

npm WARN saveError ENOENT: no such file or directory, open 'C:\Users\ao\Desktop\Sites\
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN enoent ENOENT: no such file or directory, open 'C:\Users\ao\Desktop\Sites\
npm WARN heihei No description
npm WARN heihei No repository field.
npm WARN heihei No README data

npm WARN heihei No license field.
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.9 (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.9: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

+ gulp@4.0.2
added 314 packages from 217 contributors and audited 6490 packages in 30.037s
found 0 vulnerabilities

Most likely you did not initialize npm. Need to execute

npm init

Enter the required data (or just press Enter), after which the package.json file will be created and you can return to the gulp installation


events.js:174 throw er; // Unhandled 'error' event
CssSyntaxError: postcss-simple-vars: C:\Users\ao\Desktop\Sites\travel-site\app\assets\styles\modules\_large-hero.css:5:2: Undefined variable $aMadeUpVariable2

May be called, for example, by a nonexistent variable. Let's say you added a color as a variable, but nowhere has it been set.


If you start Gulp


And get something like:

SyntaxError: Unexpected identifier
      at Module._compile (internal/modules/

      at Object.Module._extensions..js (internal/modules/

      at Module.load (internal/modules/

      at tryModuleLoad (internal/modules/

      at Function.Module._load (internal/modules/

      at Module.require (internal/modules

      at require (internal/modules/

      at execute (C:\Users\ao\AppData\Roaming\npm\

      at Liftoff.handleArguments (C:\Users\ao\AppData\Roaming\npm\

      at Liftoff.execute (C:\Users\ao\AppData\Roaming\npm\

Most likely you are trying to use syntax ES2015+ and did not install babel or it works but incorrectly.

There are two ways out - to figure it out and configure, or switch to the old syntax with require.

Did you forget to signal async completion?

There are several ways to fix this error. I use the following:

const gulp = require('gulp'); gulp.task('default', function(cb) { console.log("Gulp is running!"); cb(); });


npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.9 (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.2.9: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

This is a package incompatibility warning fsevents с Windows, as you can see здесь fsevents нужен для работы с iOS поэтому can just be ignored.

Banner Image

Error - Task function must be specified

I make out this error in the Gulp series article

No PostCSS Config found in

The solution is posted in the «Postcss: No PostCSS Config found in» article

Related Articles
Concat multiple css to one
Send files via ftp with Gulp
Gulp series
Process only changed files with'change')
Copy Directory Gulp
Video Tutorials

Search on this site

Subscribe to @aofeed channel for updates

Visit Channel


Feedbak and Questions in Telegram